Skip to content
Fallow home
All docs pages

Docs home

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 that package.json names. Without it, the action installs the latest release. The version input overrides both.
  • Read Run fallow in CI to know why the check uses fallow audit.

Steps

  1. Create the workflow file below and commit it.
  2. 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: 0 gives 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 ci installs the dependencies, because fallow reads the packages in node_modules. Use the install command of your package manager.
  • command: audit runs the changed-code check against the base commit of the pull request.
  • comment: true posts 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.

SurfaceInputPermission
Analysis, annotations, job summarynonecontents: read
Sticky commentcomment: truepull-requests: write
Fallow checkcomment: truechecks: write
Review commentsreview-comments: truepull-requests: write
SARIF uploadsarif: truesecurity-events: write
Post as the Fallow appbranded-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: 0 on actions/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 set changed-since to 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.

InputDefaultDescription
commandnoneCommand 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.
confignonePath to config file (.fallowrc.json, .fallowrc.jsonc, fallow.toml, or .fallow.toml).
formatsarifOutput format (human, json, sarif, compact, markdown, codeclimate, pr-comment-github, pr-comment-gitlab, review-github, review-gitlab, badge).
sariffalseUpload SARIF to GitHub Code Scanning.
productionfalseProduction mode: exclude test/dev files, only analyze start/build scripts.
production-dead-codefalseCombined mode only: run dead-code analysis in production mode.
production-healthfalseCombined mode only: run health analysis in production mode.
production-dupesfalseCombined mode only: run duplication analysis in production mode.
fail-on-issuestrueExit with code 1 if issues are found.
changed-sincenoneOnly report issues in files changed since this git ref (requires fetch-depth: 0).
auto-changed-sincetrueAutomatically scope analysis to changed files in PR context using the base SHA (requires fetch-depth: 0).
baselinenonePath to baseline file for comparison.
save-baselinenoneSave current results as a baseline file.
fail-on-stale-baselinefalseFail the job when the loaded baseline has entries that match nothing this run.
versionnoneFallow version override.
argsnoneAdditional 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.
commentfalsePost 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-tokenautoPost PR comments and reviews as the Fallow app (branded) when the workflow grants permissions: id-token: write.
broker-urlhttps://api.fallow.cloudBase URL of the Fallow token broker used to mint the branded app token.
annotationstrueEmit findings as inline PR annotations via workflow commands (no Advanced Security required).
review-commentsfalsePost findings as inline PR review comments with rich markdown formatting (code blocks, tables, links, suggestions).
review-guidancefalseAppend collapsed "What to do" guidance blocks to inline review comments.
review-idnoneIsolate inline comments when multiple Fallow review jobs target the same pull request.
max-annotations50Maximum number of inline annotations to emit (default: 50).
max-comments50Maximum number of inline review comments + items in the sticky details table (default: 50).
comment-layoutdefaultSticky PR comment layout: default, compact, gate-only, or details.
comment-idnoneSticky-comment marker id, embedded in the HTML comment that identifies fallow's comment for upsert.
summary-scopeallSticky 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-filteraddedDiff-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-filenonePath to a unified-diff file.
api-retries3Maximum HTTP retry attempts for fallow ci reconcile-review and the bash gh-api wrappers.
api-retry-delay2Floor delay in seconds between rate-limited retries.
dupes-modemildDetection mode for dupes command (strict, mild, weak, semantic).
min-tokensnoneMinimum token count for a clone (dupes command).
min-linesnoneMinimum line count for a clone (dupes command).
thresholdnoneFail if duplication exceeds this percentage (dupes command, 0 = no limit).
skip-localfalseOnly report cross-directory duplicates (dupes command).
cross-languagefalseStrip TypeScript type annotations for clone matching between TypeScript and JavaScript (dupes command).
ignore-importsfalseExclude import declarations from clone detection (dupes command). With false, duplicates.ignoreImports applies, and its default true also leaves imports out.
workspacenoneScope output to one or more workspaces.
changed-workspacesnoneGit-derived monorepo scoping: scope output to workspaces containing any file changed since REF (e.g., 'origin/main').
max-cyclomaticnoneMaximum cyclomatic complexity threshold (health command, default: 20).
max-cognitivenoneMaximum cognitive complexity threshold (health command, default: 15).
max-crapnoneMaximum CRAP score threshold (health and audit commands, default: 30.0).
max-file-linesnoneMaximum physical lines per file (health command, default: 0, off).
coveragenoneTest 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-coveragenonePath to paid runtime coverage input for the health command: a V8 coverage directory, V8 JSON file, or Istanbul coverage-final.json.
coverage-rootnoneRebase Istanbul file paths before matching coverage or runtime coverage input (health and audit commands).
min-invocations-hotnoneHot-path threshold for runtime coverage findings (health command, default: 100).
min-observation-volumenoneMinimum observation volume required for high-confidence runtime coverage verdicts (health command).
low-traffic-thresholdnoneFraction of total trace volume below which an invoked function is classified as low_traffic instead of active (health command).
topnoneShow only the N worst offenders (health and dupes commands).
sortnoneSort order for health results: cyclomatic (default), cognitive, lines, or severity (health command).
file-scoresfalseCompute per-file maintainability index (health command).
hotspotsfalseIdentify files that are both complex and frequently changing (health command).
targetsfalseShow ranked refactoring recommendations (health command).
complexityfalseShow only complexity findings section (health command).
sincenoneGit history window for hotspot analysis: durations (6m, 90d, 1y) or ISO dates (health command).
min-commitsnoneMinimum commits for a file to appear in hotspot ranking (health command, default: 3).
scorefalseCompute health score (0-100 with letter grade).
min-severitynonehealth command only: fail when a complexity finding reaches this severity (moderate, high, critical).
min-scorenonehealth command only: fail when the health score drops below this threshold (0-100).
fail-on-empty-analysisfalseFail the job when the run analyzed no source file at all, so every count it reports is zero because nothing was measured.
save-snapshotnoneSave vital signs snapshot to .fallow/snapshots/ for trend tracking.
trendnoneCompare current metrics against the most recent saved snapshot and show per-metric deltas.
issue-typesnoneComma-separated issue types to report (dead-code and architecture commands).
include-entry-exportsfalseReport unused exports in entry files instead of auto-marking them as used.
type-awareautoEnable optional project-wide TypeScript semantic evidence.
type-aware-projectsnoneComma-separated tsconfig paths for type-aware analysis.
type-aware-requirenoneSemantic completeness policy: best-effort or complete. complete fails the action when semantic analysis is partial or unavailable, including valid zero-finding JSON runs.
gatenoneAudit verdict gate: new-only (default) fails only introduced findings, all fails on every finding in changed files.
worsenednoneAudit 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-gatenoneSecurity regression gate: new fails on candidates introduced on changed lines, newly-reachable fails on existing candidates that became reachable from entry points.
dead-code-baselinenonePath to a dead-code baseline for the audit command.
health-baselinenonePath to a health baseline for the audit command and the combined run (empty command).
dupes-baselinenonePath to a duplication baseline for the audit command and the combined run (empty command).
fail-on-regressionfalseExit with code 1 if issue counts regressed compared to baseline (dead-code and architecture commands).
tolerance0Allowed regression tolerance before failing (e.g. "2%" or "5") (dead-code and architecture commands).
regression-baselinenonePath to regression baseline file for comparison (dead-code and architecture commands).
save-regression-baselinenoneSave current results as a regression baseline file (dead-code and architecture commands).
dry-runtruePreview changes without modifying files (fix command, default: true for CI safety).
no-cachefalseDisable incremental parse cache (force full re-parse of all files).
threadsnoneNumber of parser threads (default: available CPU cores).
onlynoneRun only these analyses when no command is specified or the command is audit (comma-separated: dead-code,architecture,dupes,health).
skipnoneSkip these analyses when no command is specified or the command is audit (comma-separated: dead-code,architecture,dupes,health).
mutationfalseRun fallow mutation before the analysis.
mutation-scopechangedMutation 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-budget10mTime budget of the mutation run, for example 90s, 10m or 1h.
mutation-max-mutantsnoneMaximum number of covered mutants that the mutation run executes.
mutation-min-scorenoneMinimum mutation score in percent (0 to 100).

Outputs

OutputDescription
resultsPath to JSON results file.
sarifPath to SARIF results file.
issuesNumber 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).
verdictAudit verdict (pass/warn/fail).
gateAudit gate (new-only/all) or security gate (new/newly-reachable) that was applied.
changed-files-unavailabletrue when the analyze step could not enumerate PR-changed files (transient GitHub API failure, expired token, missing permissions); false on the happy path.
baseline-entriesEntries in the loaded baseline.
baseline-matchedBaseline entries that matched a current finding.
baseline-stale-entriesBaseline entries that matched nothing this run.
baseline-advisoryWhich staleness advisory the baseline earned: none, partial, or zero-overlap.
baseline-change-scopedtrue when the run behind these numbers analyzed only part of the project, so the baseline could not be judged.
baseline-scope-reasonsNames 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-unrecognisedtrue 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-byThe 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-tripstrue 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-pathThe baseline the run compared against, as the baseline input spelled it.
gates-failedComma-separated names of the gates whose status is fail.
gates-warnedComma-separated names of the gates whose status is warn.
gates-skippedComma-separated names of the gates that stood down without judging the run.
gates-passedComma-separated names of the gates that ran and passed.
analysis-degradedtrue when the run recorded a diagnostic meaning its findings were computed over less than the whole project.
requests-unappliedComma-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-reasonReason the Post review comments step skipped posting (pagination_failure / none).
mutation-outcomeOutcome of the mutation step: ok, skipped, gate-failed, tool-failed, refused or interrupted.
mutation-completionCompletion of the mutation run: complete or partial.
mutation-scoreMutation score in percent, for example 87.5.
mutation-resultsPath to the mutation report (fallow-mutation.json).
mutation-report-renderedtrue 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-failedtrue when a dedup lookup failed on the Post PR comment or Post review comments step.