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: auditruns a changed-code check: the analyses on the files that the pull request changes, with one verdict.fetch-depth: 0gives the job the full git history, so fallow can compare the branch with its base.npm ciinstalls your dependencies. Fallow reads the packages innode_modules. Use the install command of your package manager.comment: trueposts the result as a comment and as a check named Fallow. The comment needspull-requests: write, and the check needschecks: 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:
| Verdict | Meaning | Check |
|---|---|---|
pass | The change adds no finding. | Passes. |
warn | The change adds only findings at the warn level, for example a clone group. | Passes. |
fail | The 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: auditchecks only the code that a pull request changes.- The verdict is
pass,warnorfail. Onlyfailfails 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.