Fallow in GitHub Actions
Add the fallow GitHub Action to check each pull request, with code scanning, review comments, monorepo jobs, inputs and outputs.
Your repository runs on GitHub, and you want each pull request checked before a reviewer reads it. The fallow GitHub Action runs the changed-code check and posts the result on the pull request: a comment, a check named Fallow, and an annotation on each finding line. The reviewer then sees a new unused export, such as cartTotalCents in the demo project, without a look into the job log. This page gives the workflow first, then the variants, the permissions and each input.
Before you start
- Add fallow to the development dependencies of the project:
npm install --save-dev fallow. The action installs the version thatpackage.jsonnames. Without it, the action installs the latest release. Theversioninput overrides both. - Read Run fallow in CI to know why the check uses
fallow audit.
Steps
- Create the workflow file below and commit it.
- Open a pull request that changes code.
# .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
Each line of the workflow has a reason:
fetch-depth: 0gives the job the history of the base branch. With a shallow clone, the action fetches the commits that it needs to find the merge base.npm ciinstalls the dependencies, because fallow reads the packages innode_modules. Use the install command of your package manager.command: auditruns the changed-code check against the base commit of the pull request.comment: trueposts a sticky comment and a check named Fallow.
fallow-rs/fallow@v3 selects the action. The action and the fallow version that it installs are separate, so a new fallow release does not need a change of this line.
Check the result
In the demo project, the pull request that adds cartTotalCents gets the verdict fail, and the job fails (see Exit codes and gates). The pull request shows the comment, the check, an annotation on each finding in the Files changed tab, and a job summary. What fallow posts on a pull request shows each one with its real text.
Variants
The workflow above fits most repositories. Each variant below changes one part of it, for a team that adopts fallow step by step, for code scanning, or for a monorepo.
Report only
A project with many findings may not want a failed check on day one. To see the findings before the check can block a merge, add fail-on-issues: false. The comment and the annotations stay. Remove the line when your team is ready for the gate.
Full analysis on the default branch
The audit compares a change with its base, so it has nothing to check on a push to main. To see the full state of the project, run all analyses on a schedule. An empty command runs all analyses:
# .github/workflows/fallow-main.yml
name: Fallow main
on:
schedule:
- cron: "0 6 * * 1"
jobs:
fallow:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- uses: fallow-rs/fallow@v3
with:
fail-on-issues: false
Upload SARIF to code scanning
Add sarif: true to the with block of the fallow step, and add security-events: write to the permissions block of the workflow. The action then uploads a SARIF file to GitHub code scanning with the category fallow. You do not need a separate upload step.
Code scanning is free on a public repository. A private or internal repository needs GitHub Advanced Security. Without it, the action skips the upload with a warning, and the job continues.
Review comments on lines
The sticky comment lists the findings in one place. To put each finding next to its line instead, set review-comments: true to post one review with a comment on each finding line. A comment can hold a suggestion that you apply with one click. When this input is on, the action posts no annotations. Add review-guidance: true to append a collapsed "What to do" block to each comment.
Monorepo: one job for each workspace
One job at the repository root checks all workspaces in one run, and fallow follows the imports between them. When each team wants its own comment and its own failed job, run one job for each workspace with a matrix. Give each job its own review-id, so that the jobs do not resolve the review comments of each other:
strategy:
matrix:
workspace: ["@acme/web", "@acme/api"]
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- run: npm ci
- uses: fallow-rs/fallow@v3
with:
command: audit
comment: true
review-comments: true
workspace: ${{ matrix.workspace }}
review-id: ${{ matrix.workspace }}
When workspace names one workspace, the action adds the workspace name to the id of the sticky comment, so each job has its own comment. Monorepos shows more ways to scope a run.
Mutation testing
The audit does not show that your tests catch a bug in the change. Set mutation: true to run fallow mutation on the lines that the pull request adds, before the analysis. The step runs your tests, so install the dependencies first. The default time budget is 10m. The comment and the job summary then show a "Mutation testing" section, and each survived mutant on a changed line becomes a finding. The step runs only on the pull_request, push, schedule, workflow_dispatch and merge_group events. It refuses pull_request_target, because that event gives the job the secrets of the base repository.
Permissions and tokens
The workflow and its variants write to several places on GitHub, and each place needs a permission of the job token. A job with a permissions block gets only the permissions that the block lists, so add a line for each surface that you turn on.
| Surface | Input | Permission |
|---|---|---|
| Analysis, annotations, job summary | none | contents: read |
| Sticky comment | comment: true | pull-requests: write |
| Fallow check | comment: true | checks: write |
| Review comments | review-comments: true | pull-requests: write |
| SARIF upload | sarif: true | security-events: write |
| Post as the Fallow app | branded-token (default auto) | id-token: write |
Without id-token: write, the comments come from github-actions[bot]. With it, the action gets a short-lived token of the Fallow GitHub App, and the app posts the comments. Without checks: write, the action posts the comment and writes the warning Failed to post Fallow check run.
A pull request from a fork gets a read-only token. The comment and the review then fail. The annotations and the job summary need no write token, so they still show.
If it fails
The action writes a warning in the job log for most problems. Find the warning text in this list:
- Warning "found no merge base". The clone is too shallow. Set
fetch-depth: 0onactions/checkout. - Warning "SARIF upload skipped". The repository is private or internal and has no GitHub Advanced Security. Remove
sarif: true. - The audit warns that it compared no changed file. The workflow ran on a push to the default branch. Run the audit on
pull_request, or setchanged-sinceto the ref to compare with. - No comment on the pull request. Check the permissions in the table above. On a fork, use the annotations and the job summary.
- Many unused dependencies. The job did not install the dependencies before the action.
Reference
Inputs
This table lists each input with the first sentence of its description in action.yml. Each input is optional. Use args to pass a global option that has no input.
An input with the default false that matches a CLI option, for example production, include-entry-exports or ignore-imports, passes that option only when you set it to true. With false, the action passes nothing, and the config file or the default of the CLI applies.
| Input | Default | Description |
|---|---|---|
command | none | Command to run: dead-code (unused code), architecture (import cycles, boundaries and policy rules), dupes (code duplication), health (complexity), audit (changed-code check), security (security candidates), fix (auto-remove unused code). |
root | . | Project root directory. |
config | none | Path to config file (.fallowrc.json, .fallowrc.jsonc, fallow.toml, or .fallow.toml). |
format | sarif | Output format (human, json, sarif, compact, markdown, codeclimate, pr-comment-github, pr-comment-gitlab, review-github, review-gitlab, badge). |
sarif | false | Upload SARIF to GitHub Code Scanning. |
production | false | Production mode: exclude test/dev files, only analyze start/build scripts. |
production-dead-code | false | Combined mode only: run dead-code analysis in production mode. |
production-health | false | Combined mode only: run health analysis in production mode. |
production-dupes | false | Combined mode only: run duplication analysis in production mode. |
fail-on-issues | true | Exit with code 1 if issues are found. |
changed-since | none | Only report issues in files changed since this git ref (requires fetch-depth: 0). |
auto-changed-since | true | Automatically scope analysis to changed files in PR context using the base SHA (requires fetch-depth: 0). |
baseline | none | Path to baseline file for comparison. |
save-baseline | none | Save current results as a baseline file. |
fail-on-stale-baseline | false | Fail the job when the loaded baseline has entries that match nothing this run. |
version | none | Fallow version override. |
args | none | Additional arguments to pass to fallow (space-separated). |
artifacts-dir | . | Directory for generated action artifacts such as fallow-results.json, fallow-results.sarif, fallow-stderr.log, and fallow-analysis-args.sh. |
comment | false | Post results as a PR comment and Fallow Check Run (requires pull-requests: write for the comment and checks: write for the check). |
github-token | $\{\{ github.token \}\} | GitHub token for PR comments and SARIF upload. |
branded-token | auto | Post PR comments and reviews as the Fallow app (branded) when the workflow grants permissions: id-token: write. |
broker-url | https://api.fallow.cloud | Base URL of the Fallow token broker used to mint the branded app token. |
annotations | true | Emit findings as inline PR annotations via workflow commands (no Advanced Security required). |
review-comments | false | Post findings as inline PR review comments with rich markdown formatting (code blocks, tables, links, suggestions). |
review-guidance | false | Append collapsed "What to do" guidance blocks to inline review comments. |
review-id | none | Isolate inline comments when multiple Fallow review jobs target the same pull request. |
max-annotations | 50 | Maximum number of inline annotations to emit (default: 50). |
max-comments | 50 | Maximum number of inline review comments + items in the sticky details table (default: 50). |
comment-layout | default | Sticky PR comment layout: default, compact, gate-only, or details. |
comment-id | none | Sticky-comment marker id, embedded in the HTML comment that identifies fallow's comment for upsert. |
summary-scope | all | Sticky PR summary comment scope: 'all' (default, include project-level dependency/catalog/override findings even when their anchor line is outside the diff) or 'diff' (apply the diff filter to those findings too). |
diff-filter | added | Diff-aware finding filter: 'added' (default, only findings on PR-added lines), 'diff_context' (added lines plus surrounding context), 'file' (any file touched by the PR), 'nofilter' (every finding). |
diff-file | none | Path to a unified-diff file. |
api-retries | 3 | Maximum HTTP retry attempts for fallow ci reconcile-review and the bash gh-api wrappers. |
api-retry-delay | 2 | Floor delay in seconds between rate-limited retries. |
dupes-mode | mild | Detection mode for dupes command (strict, mild, weak, semantic). |
min-tokens | none | Minimum token count for a clone (dupes command). |
min-lines | none | Minimum line count for a clone (dupes command). |
threshold | none | Fail if duplication exceeds this percentage (dupes command, 0 = no limit). |
skip-local | false | Only report cross-directory duplicates (dupes command). |
cross-language | false | Strip TypeScript type annotations for clone matching between TypeScript and JavaScript (dupes command). |
ignore-imports | false | Exclude import declarations from clone detection (dupes command). With false, duplicates.ignoreImports applies, and its default true also leaves imports out. |
workspace | none | Scope output to one or more workspaces. |
changed-workspaces | none | Git-derived monorepo scoping: scope output to workspaces containing any file changed since REF (e.g., 'origin/main'). |
max-cyclomatic | none | Maximum cyclomatic complexity threshold (health command, default: 20). |
max-cognitive | none | Maximum cognitive complexity threshold (health command, default: 15). |
max-crap | none | Maximum CRAP score threshold (health and audit commands, default: 30.0). |
max-file-lines | none | Maximum physical lines per file (health command, default: 0, off). |
coverage | none | Test coverage for measured CRAP scores in health, audit and the bare run: an Istanbul coverage-final.json, a V8 coverage directory or one V8 JSON file. The value goes to --coverage. |
runtime-coverage | none | Path to paid runtime coverage input for the health command: a V8 coverage directory, V8 JSON file, or Istanbul coverage-final.json. |
coverage-root | none | Rebase Istanbul file paths before matching coverage or runtime coverage input (health and audit commands). |
min-invocations-hot | none | Hot-path threshold for runtime coverage findings (health command, default: 100). |
min-observation-volume | none | Minimum observation volume required for high-confidence runtime coverage verdicts (health command). |
low-traffic-threshold | none | Fraction of total trace volume below which an invoked function is classified as low_traffic instead of active (health command). |
top | none | Show only the N worst offenders (health and dupes commands). |
sort | none | Sort order for health results: cyclomatic (default), cognitive, lines, or severity (health command). |
file-scores | false | Compute per-file maintainability index (health command). |
hotspots | false | Identify files that are both complex and frequently changing (health command). |
targets | false | Show ranked refactoring recommendations (health command). |
complexity | false | Show only complexity findings section (health command). |
since | none | Git history window for hotspot analysis: durations (6m, 90d, 1y) or ISO dates (health command). |
min-commits | none | Minimum commits for a file to appear in hotspot ranking (health command, default: 3). |
score | false | Compute health score (0-100 with letter grade). |
min-severity | none | health command only: fail when a complexity finding reaches this severity (moderate, high, critical). |
min-score | none | health command only: fail when the health score drops below this threshold (0-100). |
fail-on-empty-analysis | false | Fail the job when the run analyzed no source file at all, so every count it reports is zero because nothing was measured. |
save-snapshot | none | Save vital signs snapshot to .fallow/snapshots/ for trend tracking. |
trend | none | Compare current metrics against the most recent saved snapshot and show per-metric deltas. |
issue-types | none | Comma-separated issue types to report (dead-code and architecture commands). |
include-entry-exports | false | Report unused exports in entry files instead of auto-marking them as used. |
type-aware | auto | Enable optional project-wide TypeScript semantic evidence. |
type-aware-projects | none | Comma-separated tsconfig paths for type-aware analysis. |
type-aware-require | none | Semantic completeness policy: best-effort or complete. complete fails the action when semantic analysis is partial or unavailable, including valid zero-finding JSON runs. |
gate | none | Audit verdict gate: new-only (default) fails only introduced findings, all fails on every finding in changed files. |
worsened | none | Audit effect of an inherited complexity finding that got worse under gate new-only: warn (default) gives at least a warn verdict, error counts it like an introduced finding, off reports only the growth of an exceeded metric as worsened. |
security-gate | none | Security regression gate: new fails on candidates introduced on changed lines, newly-reachable fails on existing candidates that became reachable from entry points. |
dead-code-baseline | none | Path to a dead-code baseline for the audit command. |
health-baseline | none | Path to a health baseline for the audit command and the combined run (empty command). |
dupes-baseline | none | Path to a duplication baseline for the audit command and the combined run (empty command). |
fail-on-regression | false | Exit with code 1 if issue counts regressed compared to baseline (dead-code and architecture commands). |
tolerance | 0 | Allowed regression tolerance before failing (e.g. "2%" or "5") (dead-code and architecture commands). |
regression-baseline | none | Path to regression baseline file for comparison (dead-code and architecture commands). |
save-regression-baseline | none | Save current results as a regression baseline file (dead-code and architecture commands). |
dry-run | true | Preview changes without modifying files (fix command, default: true for CI safety). |
no-cache | false | Disable incremental parse cache (force full re-parse of all files). |
threads | none | Number of parser threads (default: available CPU cores). |
only | none | Run only these analyses when no command is specified or the command is audit (comma-separated: dead-code,architecture,dupes,health). |
skip | none | Skip these analyses when no command is specified or the command is audit (comma-separated: dead-code,architecture,dupes,health). |
mutation | false | Run fallow mutation before the analysis. |
mutation-scope | changed | Mutation scope: changed (the lines that the PR diff adds), all (each source file), or a list of files and directories relative to root, separated by spaces or commas. |
mutation-time-budget | 10m | Time budget of the mutation run, for example 90s, 10m or 1h. |
mutation-max-mutants | none | Maximum number of covered mutants that the mutation run executes. |
mutation-min-score | none | Minimum mutation score in percent (0 to 100). |
Outputs
| Output | Description |
|---|---|
results | Path to JSON results file. |
sarif | Path to SARIF results file. |
issues | Number of issues (dead-code and architecture), clone groups (dupes), security candidates (security), introduced findings counted by the audit verdict (audit), or fixes proposed/applied (fix). |
verdict | Audit verdict (pass/warn/fail). |
gate | Audit gate (new-only/all) or security gate (new/newly-reachable) that was applied. |
changed-files-unavailable | true when the analyze step could not enumerate PR-changed files (transient GitHub API failure, expired token, missing permissions); false on the happy path. |
baseline-entries | Entries in the loaded baseline. |
baseline-matched | Baseline entries that matched a current finding. |
baseline-stale-entries | Baseline entries that matched nothing this run. |
baseline-advisory | Which staleness advisory the baseline earned: none, partial, or zero-overlap. |
baseline-change-scoped | true when the run behind these numbers analyzed only part of the project, so the baseline could not be judged. |
baseline-scope-reasons | Names of the channels that narrowed the run, in the order fallow publishes them, separated by a comma and a space (for example "changed-since, production"). |
baseline-unrecognised | true when the loaded file carries no key the running command writes into its own baselines, so it is a baseline another command saved or an object with nothing of that command in it. |
baseline-saved-by | The command that saved the loaded baseline (dead-code, dupes or health), when baseline-unrecognised is true and the file names a writer that fallow knows. |
baseline-gate-trips | true when the baseline has entries that match nothing and the run could judge it, or when the loaded file is not this command's own baseline. |
baseline-path | The baseline the run compared against, as the baseline input spelled it. |
gates-failed | Comma-separated names of the gates whose status is fail. |
gates-warned | Comma-separated names of the gates whose status is warn. |
gates-skipped | Comma-separated names of the gates that stood down without judging the run. |
gates-passed | Comma-separated names of the gates that ran and passed. |
analysis-degraded | true when the run recorded a diagnostic meaning its findings were computed over less than the whole project. |
requests-unapplied | Comma-separated names of the narrowing requests the run could not apply, each with its reason in parentheses (for example "changed-since (git-failed)"). |
post-skipped-reason | Reason the Post review comments step skipped posting (pagination_failure / none). |
mutation-outcome | Outcome of the mutation step: ok, skipped, gate-failed, tool-failed, refused or interrupted. |
mutation-completion | Completion of the mutation run: complete or partial. |
mutation-score | Mutation score in percent, for example 87.5. |
mutation-results | Path to the mutation report (fallow-mutation.json). |
mutation-report-rendered | true when the installed fallow can render the mutation result (fallow report --mutation-report), so the PR comment, the review, the annotations and the job summary show it. false for an older fallow. |
dedup-lookup-failed | true when a dedup lookup failed on the Post PR comment or Post review comments step. |
Related
- Next: What fallow posts on a pull request. It shows how to read the comment, the check and the annotations.
fallow audit- GitLab CI