Skip to content
Fallow home
All docs pages

Docs home

Check each pull request

Add one GitHub workflow that runs fallow audit on each pull request, and read the comment and the verdict.

Your project has findings today, and each new pull request can add more. Here, you add one workflow file, and from then on fallow checks the code that each pull request changes. It posts a comment on the pull request, and it fails the check when the change adds a problem. Old findings do not fail the check, so you can add the workflow to a project with hundreds of findings.

Before you start

  • Your repository is on GitHub, and GitHub Actions is turned on.
  • You did the first run and know how to read a report.

Add the workflow

Create this file in your repository and commit it:

# .github/workflows/fallow.yml
name: Fallow

on: pull_request

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  fallow:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm ci
      - uses: fallow-rs/fallow@v3
        with:
          command: audit
          comment: true

What each part does:

  • command: audit runs a changed-code check: the analyses on the files that the pull request changes, with one verdict.
  • fetch-depth: 0 gives the job the full git history, so fallow can compare the branch with its base.
  • npm ci installs your dependencies. Fallow reads the packages in node_modules. Use the install command of your package manager.
  • comment: true posts the result as a comment and as a check named Fallow. The comment needs pull-requests: write, and the check needs checks: write.

The action installs the fallow version that your package.json names. When package.json does not name fallow, the action installs the latest release.

In a monorepo, keep the workflow at the repository root: one job checks all workspaces, and fallow follows the imports between them. The action saves the .fallow folder in the GitHub Actions cache, so a later run parses only the files that changed. By default, the audit also analyzes the base of the pull request to find the old findings, and that step takes extra time. GitHub Actions shows a job for each workspace, and the other inputs.

Open a pull request

Open a pull request that changes code. In the demo project, a pull request adds src/services/cart-report.ts, with the new unused export cartTotalCents and a copy of a block that two other files already have. Fallow posts this comment:

### Quality gate failed

Fallow audit report, 2 findings: 1 error, 1 warning.

> Gates: failed audit-verdict.

<details>
<summary>Dead code (1)</summary>

| Severity | Rule | Location | Description |
| --- | --- | --- | --- |
| error | [`fallow/unused-export`](https://fallow.tools/docs/explanations/dead-code/#unused-exports) | `src/services/cart-report.ts:25` | Export `cartTotalCents` is never imported by other modules |

</details>

<details>
<summary>Duplication (1)</summary>

| Severity | Rule | Location | Description |
| --- | --- | --- | --- |
| warning | [`fallow/code-duplication`](https://fallow.tools/docs/explanations/duplication/#clone-groups) | `src/services/cart-report.ts:7` | 17 lines repeat in 3 places (clone group dup:f42424e8) |

</details>

On GitHub, each <details> block is a collapsed table, and each rule links to a page that explains it. The comment shows only the findings on the lines that the pull request adds. The heading and the Fallow check follow the verdict of the audit:

VerdictMeaningCheck
passThe change adds no finding.Passes.
warnThe change adds only findings at the warn level, for example a clone group.Passes.
failThe change adds a finding at the error level, for example an unused export.Fails.

This pull request gets fail because of cartTotalCents, and fallow audit exits with code 1, so the job fails. Remove the export and push again: fallow updates the same comment, and the verdict becomes warn. When a pull request has no findings, fallow posts no new comment.

Why old findings do not count

The verdict counts only the findings that the pull request adds. The demo project still has cancelOrder and left-pad from the first run, but this pull request does not add them, so they do not change the verdict. An old finding in a file that the pull request changes does not fail the check either. Changed code explains how fallow tells new findings from old ones. To clean the old findings step by step, follow Adopt fallow in an existing project.

Other CI systems

On another CI system, run the audit as a command in the job. Give the branch to compare with:

npx fallow audit --base origin/main --quiet

The job fails on exit code 1. CI integration shows the setup for other systems. For GitLab, fallow has a CI template that posts merge request comments: see GitLab CI.

What you learned

  • command: audit checks only the code that a pull request changes.
  • The verdict is pass, warn or fail. Only fail fails the check.
  • Old findings stay in the report of a full run, but they do not block a pull request.

Next

The same check can run before the code reaches a pull request, in the loop of your coding agent: Use fallow with a coding agent.