CI integration

1. 1

   Add the action

   Add fallow to your workflow file:

   name: Fallow analysis
   on: [push, pull_request]
   
   jobs:
     fallow:
       runs-on: ubuntu-26.04
       steps:
         - uses: actions/checkout@v4
         - uses: fallow-rs/fallow@v3
           with:
             format: sarif

   By default, this runs all analyses (dead code, duplication, and complexity). To run one analysis, set the command input.

   Note.

   When you enable comment: true or review-comments: true, grant the job contents: read, id-token: write, pull-requests: write, and checks: write. With id-token: write, the Action gets a short-lived Fallow GitHub App token, and fallow-cloud[bot] posts the feedback. Without id-token: write, the analysis and the posts still run, as github-actions[bot].

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

2. 2

   Configure inputs

   The action takes these inputs:

   Input	Default	Description
   command	-- (all)	Command to run (dead-code, architecture, dupes, health, audit, security, fix, or empty for all). Legacy alias: check = dead-code. architecture reports import cycles, boundary violations, and policy violations. See fallow architecture.
   root	.	Project root directory
   config	--	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, or badge)
   sarif	false	Upload SARIF to GitHub Code Scanning. Needs permissions: security-events: write.
   artifacts-dir	.	Directory for the files that the action writes, such as fallow-results.json and fallow-results.sarif. Relative to the workflow workspace.
   production	false	Turn on production mode for every analysis
   production-dead-code	false	Combined mode only: per-analysis production mode for dead-code
   production-health	false	Combined mode only: per-analysis production mode for health
   production-dupes	false	Combined mode only: per-analysis production mode for duplication
   fail-on-issues	true	Exit with code 1 when there are issues
   issue-types	--	Comma-separated issue types to report (dead-code and architecture commands). For architecture, the values are cycles, boundaries and policy.
   include-entry-exports	false	Report unused exports in entry files and do not mark them as used. This catches typos in framework exports (dead-code analysis).
   fail-on-regression	false	Exit with code 1 when the issue counts increase compared to the regression baseline (dead-code command)
   tolerance	0	Allowed increase before a regression fails, for example 2% or 5 (dead-code command)
   regression-baseline	--	Path to the regression baseline file to compare against (dead-code command)
   save-regression-baseline	--	Save the current results as a regression baseline file (dead-code command)
   changed-since	--	Only check files changed since this ref
   auto-changed-since	true	In a PR, check only changed files, compared to the base SHA. Ignored when changed-since is set.
   baseline	--	Path to a baseline file to compare against. With command: audit, the action rejects it with exit 2. Use dead-code-baseline, health-baseline, or dupes-baseline for audit. With command: fix, the action also rejects it with exit 2, because fix does not load a baseline. When command is empty, it holds the dead-code baseline only: pass the health and duplication baselines with health-baseline and dupes-baseline.
   save-baseline	--	Save the current results as a baseline file. With command: audit, the action rejects it with exit 2, because audit runs three analyses with different baseline formats. command: fix also rejects it with exit 2. The file must be inside the project, its Git work tree, the CI workspace, RUNNER_TEMP, or the system temp directory. See Save destinations.
   fail-on-stale-baseline	false	Fail the job when the loaded baseline has entries that match nothing in this run, or when it is a baseline of another kind. You get the staleness warning without this input: every run that loads a baseline reports it. A scoped run cannot judge a whole-project baseline, so a narrowed run first reads the baseline again over the whole project. This input only decides if that verdict fails the job. It does not depend on fail-on-issues, because a fully stale baseline on a now-clean project reports zero issues. When the run still cannot cover the whole project (production, workspace, changed-workspaces, or a positional path in args), the gate warns and does not judge.
   min-score	--	command: health only: fail when the health score is below this threshold (0-100). Implies --score. Unless you set a health section input, the action adds --complexity, so annotations, SARIF, and the PR comment still have content. target_thresholds and hotspot_summary do not come back. With this input, the CLI turns off its own findings rule and the count gate, so only the score decides the run. Any other command rejects it with exit 2.
   min-severity	--	command: health only: fail when a complexity finding reaches this severity (moderate, high, or critical). A finding whose complexity-* rule is warn never trips this gate. The fail-on-issues count gate is separate and still counts every finding. To gate on severity alone, set fail-on-issues: false.
   fail-on-empty-analysis	false	Fail the job when the run analyzed no source file. In that case every count is zero because the run measured nothing, not because the project is clean. By default the run warns and passes, so a repository whose scope has no source on purpose still passes.
   version	--	Fallow version to install. The Action ref does not set the fallow CLI version: uses: fallow-rs/fallow@v3 selects only the Action wrapper code. The action picks the CLI version from this input, then the fallow dependency spec in the project package.json, then latest.
   workspace	--	Limit the output to one or more workspaces (exact names, globs, ! negation; comma-separated)
   changed-workspaces	--	Limit a monorepo run to workspaces with a file changed since REF (for example origin/main). Requires fetch-depth: 0. Cannot be used with workspace. A missing ref is a hard error (exit 2). The run does not fall back to the full scope.
   comment	false	Post results as a PR comment
   review-comments	false	Post inline PR review comments from typed review-github output. Later runs resolve threads for fixed findings
   review-guidance	false	Add collapsed "What to do" guidance blocks to inline PR review comments. Requires review-comments: true
   max-comments	50	Maximum number of inline review comments, and of items in the sticky details table
   comment-layout	default	Layout of the sticky PR comment: default, compact, gate-only, or details. Use gate-only when the Check Run is the main place where you read PR findings.
   comment-id	--	Marker id of the sticky comment. The default is fallow-results, with the workspace name added when the run covers one workspace.
   summary-scope	all	Scope of the sticky PR summary. Use diff to also apply the diff filter to project-level dependency, catalog, and override findings. Inline review comments do not change.
   diff-filter	added	Show line-level findings only on added PR lines. Use diff_context, file, or nofilter for a wider review scope.
   diff-file	--	Path to a unified diff file. Fallow then limits source findings to lines in an added hunk. When you also set changed-since, the diff filter decides the findings, and changed-since still decides the file discovery.
   api-retries	3	Maximum number of HTTP retries for fallow ci reconcile-review and the GitHub API calls of the action
   api-retry-delay	2	Minimum delay in seconds between retries after a rate limit. A Retry-After header from the server overrides it.
   review-id	--	Stable identifier (1-64 characters, A-Za-z0-9._-) that keeps the inline review comments of each job separate when more than one fallow review job posts to the same pull request. See Isolating parallel review jobs.
   annotations	true	Show findings as inline PR annotations through workflow commands (no Advanced Security required). On fallow >= 3.4.2, the action renders them natively with fallow report --format github-annotations. Older binaries use a frozen legacy renderer that gets no new finding types, and the step log shows a notice to upgrade. With version: latest, you get the native path with no change on your side. The step log line fallow: annotations rendered via native github-annotations (or via jq fallback) tells you which renderer ran. The job summary follows the same rule with github-summary. Each annotation takes its level from the rule severity of the finding, so an error finding gives ::error. See Levels in CI formats.
   max-annotations	50	Maximum number of inline annotations. On the native path, the cap applies to the rendered stream. GitHub shows at most 10 annotations per type per step.
   github-token	$\{\{ github.token \}\}	GitHub token for PR comments and SARIF upload
   branded-token	true	When the workflow grants id-token: write, post comments and reviews with a short-lived Fallow GitHub App token. When that token is not available, the action uses github-token.
   broker-url	https://api.fallow.cloud	Fallow token broker that exchanges the workflow identity for the branded app token.
   dupes-mode	mild	Detection mode for the dupes command
   min-tokens	--	Minimum token count for a clone (dupes command)
   min-lines	--	Minimum line count for a clone (dupes command)
   threshold	--	Fail when duplication is more than this % (dupes command)
   skip-local	false	Only report cross-directory duplicates (dupes command)
   cross-language	false	Remove TypeScript type annotations, so TypeScript and JavaScript clones match (dupes command)
   ignore-imports	false	Exclude import declarations from clone detection (dupes command)
   top	--	Show only the N worst offenders (health and dupes commands)
   max-cyclomatic	--	Maximum cyclomatic complexity (health command, CLI default 20)
   max-cognitive	--	Maximum cognitive complexity (health command, CLI default 15)
   sort	--	Sort order for health results: cyclomatic (default), cognitive, lines, or severity (health command)
   complexity	false	Show only the complexity findings section (health command)
   file-scores	false	Compute the maintainability index for each file (health command)
   hotspots	false	Find files that are complex and change often (health command)
   targets	false	Show ranked refactoring recommendations (health command)
   since	--	Git history window for hotspots: a duration (6m, 90d, 1y) or an ISO date (health command)
   min-commits	--	Minimum number of commits for a file in the hotspot ranking (health command, CLI default 3)
   score	false	Compute the health score (0-100 with letter grade). Adds the health delta header to PR comments (health and bare command)
   trend	false	Compare the current metrics with the most recent saved snapshot. Implies score (health and bare command)
   save-snapshot	--	Save a vital signs snapshot for trend tracking. Set true for the default path, or give a custom path (health and bare command)
   type-aware	auto	Optional project-wide TypeScript semantic evidence: true, false, or auto. With auto, the action installs the matching fallow-type-aware sidecar when your fallow config turns on typeAware, and the config decides. true also passes --type-aware. false skips the sidecar and passes --no-type-aware. Does not report compiler diagnostics or generic typed lint findings.
   type-aware-projects	""	Comma-separated tsconfig paths. Empty uses automatic project discovery.
   type-aware-require	""	best-effort or complete. When empty, the action passes no value, and your config or the CLI default (best-effort) decides. Use complete to fail when semantic analysis is partial or unavailable, including valid zero-finding runs. The action passes the value to fallow only with type-aware: true. With auto or false, the action checks the result itself after the run, so complete also fails a run in which type-aware analysis did not run.
   dry-run	true	Preview changes without modifying files (fix command)
   coverage	--	Path to Istanbul coverage-final.json for accurate per-function CRAP scores (health and audit commands)
   coverage-root	--	Absolute prefix to remove from Istanbul file paths before matching (health and audit commands). Use it when CI or Docker generated the coverage under a different checkout root, for example /home/runner/work/myapp.
   runtime-coverage	--	Path to runtime coverage input for the health command: a V8 coverage directory, a V8 JSON file, or an Istanbul coverage-final.json. A single local capture is free. Continuous or multi-capture monitoring needs a license. See fallow license.
   min-invocations-hot	--	Hot-path threshold for runtime coverage findings (health command, CLI default 100)
   min-observation-volume	--	Minimum observation volume for high-confidence runtime coverage verdicts (health command)
   low-traffic-threshold	--	Share of the total trace volume below which an invoked function is low_traffic and not active (health command)
   max-crap	30.0	CRAP score threshold (health and audit commands). Functions at or above this score count toward the verdict.
   gate	new-only	Audit verdict gate. new-only fails only on findings that the changeset introduces. all fails on every finding in changed files.
   security-gate	--	Security delta gate for command: security. new fails only on changed-line candidates. newly-reachable fails only on candidates that became reachable from entry points, and needs a base ref from changed-since or PR auto-scoping. A gated security failure exits with code 8, and the issues output counts only the candidates that match the gate. The PR comment and review renderers do not support security envelopes yet, so the action skips them for this command.
   dead-code-baseline / health-baseline / dupes-baseline	--	Baseline file paths for each analysis in the audit command (saved by `fallow dead-code
   no-cache	false	Turn off the incremental parse cache and parse all files again
   threads	--	Number of parser threads (default: the number of CPU cores)
   only	--	Without command: run only these analyses (comma-separated: dead-code, architecture, dupes, health)
   skip	--	Without command: skip these analyses (comma-separated: dead-code, architecture, dupes, health)
   args	--	More arguments to pass to fallow. With command: audit, the action rejects --fail-on-stale-baseline with exit 2. An audit analyzes only the files that changed against its base, so it cannot judge a whole-project baseline.

3. 3

   Upload SARIF (optional)

   To get inline annotations on the PR diff, upload the results to GitHub Code Scanning:

   - uses: fallow-rs/fallow@v3
     with:
       format: sarif
   
   - uses: github/codeql-action/upload-sarif@v4
     with:
       sarif_file: fallow-results.sarif

   Each dead-code result has a fallowFinding/v1 partial fingerprint with the finding_id of the finding. The location-based keys did not change, so code scanning does not close and reopen the open alerts after an upgrade. See SARIF output.

fallow: 8 issues found

Dead Code (3 issues)
| Type | File | Symbol | Line |
|------|------|--------|------|
| unused-export | src/utils/format.ts | formatCurrency | 12 |
| unused-export | src/utils/format.ts | formatPercentage | 28 |
| unused-file | src/legacy/oldApi.ts | n/a | n/a |

Duplication (3 clone groups, 1.8%)
| Files | Lines | Tokens |
|-------|-------|--------|
| src/tax/utils.ts ↔ src/savings/utils.ts | 25 | 92 |

Complexity (2 hotspots)
| File | Function | Cyclomatic | Cognitive |
|------|----------|------------|-----------|
| src/server/router.ts:42 | handleRequest | 28 | 34 |

Completed in 48ms

1. 1

   Include the template

   Add fallow to your .gitlab-ci.yml:

   include:
     - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'
   
   fallow:
     extends: .fallow

   This runs all analyses (dead code, duplication, and complexity) on every MR and on every push to the default branch.

2. 2

   Configure variables

   Set these CI/CD variables to change the behavior:

   Variable	Default	Description
   FALLOW_COMMAND	""	Command to run (dead-code, architecture, dupes, health, audit, security, fix, or empty for all). Legacy alias: check = dead-code. architecture reports import cycles, boundary violations, and policy violations. See fallow architecture.
   FALLOW_ROOT	.	Project root directory
   FALLOW_CONFIG	--	Path to config file
   FALLOW_PRODUCTION	""	Set to "true" to turn on production mode for every analysis. When empty, the per-analysis env and config decide.
   FALLOW_PRODUCTION_DEAD_CODE	""	Combined mode only: set to "true" or "false" to override FALLOW_PRODUCTION for dead-code. When empty, FALLOW_PRODUCTION decides.
   FALLOW_PRODUCTION_HEALTH	""	Combined mode only: set to "true" or "false" to override FALLOW_PRODUCTION for health. When empty, FALLOW_PRODUCTION decides.
   FALLOW_PRODUCTION_DUPES	""	Combined mode only: set to "true" or "false" to override FALLOW_PRODUCTION for duplication. When empty, FALLOW_PRODUCTION decides.
   FALLOW_FAIL_ON_ISSUES	true	Fail the pipeline when there are issues
   FALLOW_ISSUE_TYPES	""	Comma-separated issue types to report (dead-code and architecture commands). For architecture, the values are cycles, boundaries and policy.
   FALLOW_INCLUDE_ENTRY_EXPORTS	"false"	Report unused exports in entry files and do not mark them as used (same as --include-entry-exports)
   FALLOW_FAIL_ON_REGRESSION	"false"	Fail when the issue counts increase compared to the regression baseline (dead-code command)
   FALLOW_TOLERANCE	"0"	Allowed increase before a regression fails (dead-code command)
   FALLOW_REGRESSION_BASELINE / FALLOW_SAVE_REGRESSION_BASELINE	""	Regression baseline file to compare against, and the file to save the current results to (dead-code command)
   FALLOW_TYPE_AWARE	""	Set to "true" to turn on semantic evidence or "false" to turn it off. When empty, the repository config decides.
   FALLOW_TYPE_AWARE_PROJECTS	""	Comma-separated tsconfig paths. Empty uses automatic project discovery. The template passes each path as a separate CLI flag.
   FALLOW_TYPE_AWARE_REQUIRE	""	best-effort or complete. When empty, the repository config decides. complete fails on partial or unavailable semantic evidence. A value turns on type-aware analysis. Together with FALLOW_TYPE_AWARE: "false", the job stops with exit code 2.
   FALLOW_CHANGED_SINCE	--	Only check files changed since this ref (auto-detected in MR pipelines)
   FALLOW_BASELINE	--	Path to a baseline file to compare against. With FALLOW_COMMAND=audit, the template rejects it with exit 2. Use FALLOW_AUDIT_DEAD_CODE_BASELINE, FALLOW_AUDIT_HEALTH_BASELINE, or FALLOW_AUDIT_DUPES_BASELINE for audit. With FALLOW_COMMAND=fix, the template also rejects it with exit 2. On the bare run (empty FALLOW_COMMAND), it holds the dead-code baseline only: use FALLOW_HEALTH_BASELINE and FALLOW_DUPES_BASELINE for the others.
   FALLOW_SAVE_BASELINE	--	Save the current results as a baseline file. With FALLOW_COMMAND=audit, the template rejects it with exit 2, because audit runs three analyses with different baseline formats. FALLOW_COMMAND=fix also rejects it with exit 2.
   FALLOW_FAIL_ON_STALE_BASELINE	"false"	Fail the pipeline when the loaded FALLOW_BASELINE has entries that match nothing in this run, or when it is a baseline of another kind. You get the staleness warning without this variable: every run that loads a baseline reports it. A scoped run cannot judge a whole-project baseline, so a narrowed pipeline first reads the baseline again over the whole project. This variable only decides if that verdict fails the pipeline. It does not depend on FALLOW_FAIL_ON_ISSUES, because a fully stale baseline on a now-clean project reports zero issues. When the run still cannot cover the whole project (FALLOW_PRODUCTION, FALLOW_WORKSPACE, FALLOW_CHANGED_WORKSPACES, or a positional path in FALLOW_ARGS), the gate warns and does not judge.
   FALLOW_MIN_SCORE	""	FALLOW_COMMAND: health only: fail when the health score is below this threshold (0-100). Implies --score. Unless a health section variable is set, the template adds --complexity, so the Code Quality report and the MR note still have content. With this variable, the CLI turns off its own findings rule and the count gate.
   FALLOW_MIN_SEVERITY	""	FALLOW_COMMAND: health only: fail when a complexity finding reaches this severity (moderate, high, or critical). FALLOW_FAIL_ON_ISSUES is a separate count gate.
   FALLOW_FAIL_ON_EMPTY_ANALYSIS	"false"	Fail the pipeline when the run analyzed no source file. By default, the run warns and passes.
   FALLOW_SECURITY_GATE	""	Security delta gate for FALLOW_COMMAND: "security". new fails only on changed-line candidates. newly-reachable fails only on candidates that became reachable from entry points, and needs a base ref from FALLOW_CHANGED_SINCE or MR auto-detection. A gated security failure exits with code 8. The MR comment and review renderers do not support security envelopes yet, so the template skips them for this command.
   FALLOW_COMMENT	false	Post an MR summary comment with a collapsible section for each analysis
   FALLOW_REVIEW	false	Post inline MR discussions on changed lines with suggestion blocks for auto-fixable issues
   FALLOW_REVIEW_GUIDANCE	false	Add collapsed "What to do" guidance blocks to inline MR discussions
   FALLOW_REVIEW_ID	--	Stable identifier (1-64 characters, A-Za-z0-9._-) that keeps the inline review discussions of each job separate when more than one fallow review job posts to the same MR. See Isolating parallel review jobs.
   FALLOW_COMMENT_ID	""	Marker id of the sticky comment. When empty and the run covers one workspace, the template adds the workspace name.
   FALLOW_SUMMARY_SCOPE	all	Scope of the sticky MR summary. Use diff to also apply the diff filter to project-level dependency, catalog, and override findings. Inline review discussions do not change
   FALLOW_PR_COMMENT_LAYOUT	default	Layout of the sticky MR comment: default, compact, gate-only, or details. Use gate-only when Code Quality is the main place where you read MR findings
   FALLOW_MAX_COMMENTS	50	Maximum number of inline review comments (applies to FALLOW_REVIEW)
   FALLOW_CODEQUALITY	true	Generate a Code Quality report (inline MR annotations)
   FALLOW_VERSION	--	Fallow version to use. When empty, the template uses the fallow dependency in the project package.json, or else latest. Set it to override the local pin.
   FALLOW_SCRIPTS_REF	--	Pin the CI scripts to a git ref (tag, branch, or SHA) for reproducible builds. When empty, the template uses vendored scripts first. Else it uses the ref of the exact installed fallow version, when it can.
   FALLOW_SKIP_INSTALL	""	Set to "true" to skip npm install -g fallow and use the fallow that is already on the PATH of the job shell. If there is none, the job fails at once. See the setup gotchas step below.
   FALLOW_DIFF_FILTER	added	Show line-level findings only in added diff hunks. Use diff_context, file, or nofilter for a wider review scope.
   FALLOW_DIFF_FILE	""	Path to a unified diff file. When empty in an MR pipeline, the comment and review scripts make the diff with git diff.
   FALLOW_API_RETRIES	"3"	Maximum number of HTTP retries for fallow ci reconcile-review and the API calls of the scripts
   FALLOW_API_RETRY_DELAY	"2"	Minimum delay in seconds between retries after a rate limit. A Retry-After header from the server overrides it.
   FALLOW_WORKSPACE	--	Limit the output to one or more workspaces (exact names, globs, ! negation; comma-separated)
   FALLOW_CHANGED_WORKSPACES	--	Limit a monorepo run to workspaces with a file changed since REF. Requires full git history. Cannot be used with FALLOW_WORKSPACE. A missing ref is a hard error.
   FALLOW_DUPES_MODE	mild	Detection mode for dupes (strict, mild, weak, semantic)
   FALLOW_MIN_TOKENS / FALLOW_MIN_LINES	""	Minimum token count and minimum line count for a clone (dupes command)
   FALLOW_THRESHOLD	""	Fail when duplication is more than this % (dupes command)
   FALLOW_SKIP_LOCAL / FALLOW_CROSS_LANGUAGE / FALLOW_IGNORE_IMPORTS	"false"	Same as the --skip-local, --cross-language, and --ignore-imports flags (dupes command)
   FALLOW_MAX_CYCLOMATIC / FALLOW_MAX_COGNITIVE	""	Maximum cyclomatic and cognitive complexity (health command)
   FALLOW_TOP	""	Show only the N worst offenders (health and dupes commands)
   FALLOW_SORT	""	Sort order for health results: cyclomatic (default), cognitive, lines, or severity
   FALLOW_COMPLEXITY / FALLOW_FILE_SCORES / FALLOW_HOTSPOTS / FALLOW_TARGETS	"false"	Turn on single health report sections, the same as --complexity, --file-scores, --hotspots, and --targets
   FALLOW_SINCE / FALLOW_MIN_COMMITS	""	Git history window and minimum commit count for hotspots (health command)
   FALLOW_SCORE	false	Compute the health score (0-100 with letter grade). Adds the health delta header to MR comments (health and bare command)
   FALLOW_TREND	false	Compare the current metrics with the most recent saved snapshot. Implies FALLOW_SCORE (health and bare command)
   FALLOW_SAVE_SNAPSHOT	--	Save a vital signs snapshot for trend tracking. Set true for the default path, or give a custom path (health and bare command)
   FALLOW_COVERAGE	--	Path to Istanbul coverage-final.json for accurate per-function CRAP scores (health, audit, and default combined commands)
   FALLOW_COVERAGE_ROOT	--	Rebase Istanbul file paths before matching (health, audit, and default combined commands). Use it when CI or Docker generated the coverage under a different checkout root.
   FALLOW_PRODUCTION_COVERAGE	""	Path to runtime coverage input: a V8 coverage directory, a V8 JSON file, or an Istanbul coverage-final.json. A single local capture is free. Continuous or multi-capture monitoring needs a license. See fallow license.
   FALLOW_MIN_INVOCATIONS_HOT / FALLOW_MIN_OBSERVATION_VOLUME / FALLOW_LOW_TRAFFIC_THRESHOLD	""	Thresholds for runtime coverage verdicts (health command)
   FALLOW_MAX_CRAP	30.0	CRAP score threshold (health and audit commands)
   FALLOW_AUDIT_GATE	new-only	Audit verdict gate (new-only or all)
   FALLOW_AUDIT_DEAD_CODE_BASELINE / FALLOW_AUDIT_HEALTH_BASELINE / FALLOW_AUDIT_DUPES_BASELINE	--	Baseline file paths for each analysis in the audit command (saved by `fallow dead-code
   FALLOW_HEALTH_BASELINE / FALLOW_DUPES_BASELINE	--	Bare run only (empty FALLOW_COMMAND): the health and duplication baselines, saved by fallow health --save-baseline and fallow dupes --save-baseline. FALLOW_FAIL_ON_STALE_BASELINE judges them too. Other commands ignore them.
   FALLOW_DRY_RUN	"true"	Preview changes without modifying files (fix command)
   FALLOW_NO_CACHE	"false"	Turn off the incremental parse cache
   FALLOW_THREADS	""	Number of parser threads
   FALLOW_ONLY / FALLOW_SKIP	""	Without FALLOW_COMMAND: run only, or skip, these analyses (comma-separated)
   FALLOW_ARGS	--	More arguments (space-separated). With FALLOW_COMMAND=audit, the template rejects --fail-on-stale-baseline with exit 2. An audit analyzes only the files that changed against its base, so it cannot judge a whole-project baseline.

   Info.

   In MR pipelines, the template passes --changed-since, so the analysis covers only the files that the merge request changes. You do not need to configure this.

   Info.

   The template detects your package manager (npm, pnpm, or yarn) from the lock files. Review comments and suggestions show the correct install and uninstall commands for your project.

   Example: full MR feedback with a summary comment and inline review:

   fallow:
     extends: .fallow
     variables:
       FALLOW_COMMENT: "true"
       FALLOW_REVIEW: "true"

   Example: dead code only, with MR comments:

   fallow:
     extends: .fallow
     variables:
       FALLOW_COMMAND: "dead-code"
       FALLOW_COMMENT: "true"

   Example: import cycles, boundaries, and policy rules only:

   fallow:
     extends: .fallow
     variables:
       FALLOW_COMMAND: "architecture"

3. 3

   Code Quality reports

   The template generates a GitLab Code Quality report (CodeClimate format). GitLab shows the fallow findings as inline annotations on the MR diff. This is the GitLab equivalent of GitHub Code Scanning.

   You do not need to configure this. The template uploads the report as a CI artifact. If you run fallow yourself outside the template, --format codeclimate and its alias --format gitlab-codequality give the same JSON array that GitLab reads.

   The fingerprint of a dead-code issue comes from its finding_id, so an issue stays open when you add lines above it. On the first run after the upgrade to this fingerprint form, Code Quality shows each dead-code finding as resolved and as new one time. Duplication, health and security fingerprints did not change.

4. 4

   Rich MR comments

   Summary comment: Set FALLOW_COMMENT: "true" to post an MR comment with collapsible sections for dead code, duplication, and complexity findings. Each push updates the same comment, so the MR does not fill up with comments. To hide old project-level dependency, catalog, and override findings outside the diff in the sticky summary, set FALLOW_SUMMARY_SCOPE: "diff". When you read MR findings mainly in GitLab Code Quality, set FALLOW_PR_COMMENT_LAYOUT: "gate-only" to keep the sticky comment compact.

   Inline review: Set FALLOW_REVIEW: "true" to post inline MR discussions on changed lines. Auto-fixable issues have GitLab suggestion blocks that you apply with one click. To cap the number of inline comments, use FALLOW_MAX_COMMENTS (default: 50). To add collapsed "What to do" guidance to each inline finding, set FALLOW_REVIEW_GUIDANCE: "true". The template renders native review-gitlab envelopes with position_type, base_sha, start_sha, and head_sha from the GitLab diff refs. It then runs fallow ci reconcile-review --provider gitlab, which resolves old fallow discussions after you fix the findings.

   fallow:
     extends: .fallow
     variables:
       FALLOW_COMMENT: "true"    # Rich summary comment
       FALLOW_SUMMARY_SCOPE: "diff" # Filter project-level findings in the summary too
       FALLOW_PR_COMMENT_LAYOUT: "gate-only" # Keep the sticky summary compact
       FALLOW_REVIEW: "true"     # Inline discussions with suggestions
       FALLOW_REVIEW_GUIDANCE: "true" # Collapsed "What to do" blocks
       FALLOW_MAX_COMMENTS: "30" # Limit inline comments

5. 5

   Authentication

   MR summary comments (FALLOW_COMMENT) and inline review (FALLOW_REVIEW) need a GITLAB_TOKEN (project access token or PAT) with api scope. Set it as a CI/CD variable.

   Warning.

   The documented GitLab CI_JOB_TOKEN permissions allow you to read MR notes, but not to create, update, or delete them. When GITLAB_TOKEN is not set, the template skips the MR comment and review posts with a warning. The pipeline does not fail. You can still use CI_JOB_TOKEN to authenticate with the GitLab package registry.

6. 6

   Vendoring (offline runners)

   If your runners cannot reach raw.githubusercontent.com, vendor the template and helper scripts into your repo. Run this command once on your machine:

   npx fallow ci-template gitlab --vendor

   The command writes ci/gitlab-ci.yml and two helper scripts (ci/scripts/comment.sh, ci/scripts/review.sh) under ci/. Commit the generated files and change to a local include:

   include:
     - local: 'ci/gitlab-ci.yml'
   
   fallow:
     extends: .fallow

   The vendored template uses the local scripts and fetches nothing remote. To overwrite files that no longer match the bundled template, pass --force.

7. 7

   Setup gotchas

   • The template sets GIT_STRATEGY: "fetch". A shared template that sets GIT_STRATEGY=none then cannot leave fallow without a working tree.
   • The template sets GIT_DEPTH: "0", so --changed-since can diff against the MR base SHA without shallow-clone problems.
   • For a private GitLab npm registry, create .npmrc during the job with ${CI_PROJECT_ID} and ${CI_JOB_TOKEN}. Do not commit tokens.
   • For pnpm projects with minimumReleaseAge, add fallow and @fallow-cli/* to minimumReleaseAgeExclude when you need a just-published fallow release at once.

   To run the template with a fallow that you install yourself (for example a pnpm-catalog pin), do these steps:

   • Set FALLOW_SKIP_INSTALL: "true".
   • Override image: with your base image.
   • Make sure that your install step puts fallow on the PATH of the job shell.

   A plain pnpm install or npm install only writes node_modules/.bin/fallow. GitLab does not add that directory to PATH, so add it yourself. A job that uses extends: .fallow and defines its own before_script replaces the before_script of the template, because GitLab does not merge them. Use !reference to keep the install and script-prep block of the template:

   fallow:
     extends: .fallow
     before_script:
       - export PATH="$CI_PROJECT_DIR/node_modules/.bin:$PATH"
       - !reference [.fallow, before_script]
     variables:
       FALLOW_SKIP_INSTALL: "true"

   The job then skips npm install -g fallow and runs your exact binary, so CI gives the same result as your local lint gate. If you also enable FALLOW_COMMENT or FALLOW_REVIEW and your binary is a dev build whose --version is not an exact release (for example 2.3.0-dev), pin FALLOW_SCRIPTS_REF to a real tag or vendor ci/scripts/, so the template can still fetch the MR-integration scripts.

include:
  - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'

fallow:
  extends: .fallow
  variables:
    FALLOW_COMMENT: "true"        # Rich MR summary with collapsible sections
    FALLOW_REVIEW: "true"         # Inline discussions with suggestion blocks
    FALLOW_MAX_COMMENTS: "50"     # Cap inline review comments (default: 50)
    FALLOW_CODEQUALITY: "true"    # Code Quality report for MR annotations
    FALLOW_FAIL_ON_ISSUES: "true" # Fail pipeline on issues
    FALLOW_PRODUCTION: "true"     # Exclude test/dev files
    # FALLOW_SCRIPTS_REF: "v1.0.0" # Pin scripts to a specific version

To run fallow without the action or the template, call it directly:

- run: npx fallow --ci              # All analyses (dead code + dupes + health)
- run: npx fallow dead-code --ci    # Dead code only
- run: npx fallow dupes --ci        # Duplication only
- run: npx fallow health --ci       # Complexity hotspots only

The --ci flag turns on SARIF output, fail-on-issues, and quiet mode together. You can also set them one by one:

- run: npx fallow --fail-on-issues --format compact

PR/MR comments

To post the results as a comment, use markdown output:

- run: npx fallow dead-code --format markdown | gh pr comment ${{ github.event.pull_request.number }} --body-file -
- run: npx fallow dupes --format markdown | gh pr comment ${{ github.event.pull_request.number }} --body-file -
- run: npx fallow health --format markdown | gh pr comment ${{ github.event.pull_request.number }} --body-file -

fallow:
  extends: .fallow
  variables:
    FALLOW_COMMENT: "true"

fallow:
  script:
    - npx fallow --format markdown > fallow-report.md
    - |
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" \
        --data-urlencode "body@fallow-report.md"
  rules:
    - if: $CI_MERGE_REQUEST_IID

Consuming review envelopes from your own code

Use this path when your CI runners cannot use remote includes, do not have jq, or cannot give API tokens to third-party binaries. Run fallow to get the typed review-github or review-gitlab envelope. Then POST the comments yourself from the job that already has the token. Fallow does the rendering, the fingerprints, and the DiffNote positions. Your code only loops over the comments and POSTs each one.

Envelope shape

gh pr diff $PR_NUMBER | npx fallow audit --diff-stdin --format review-github
glab mr diff $CI_MERGE_REQUEST_IID | npx fallow audit --diff-stdin --format review-gitlab

Output:

{
  "event": "COMMENT",
  "body": "### Fallow audit\n\n3 inline findings selected for GitHub review.\n\n<!-- fallow-review -->\n\n<!-- fallow-fingerprint:v3: 06bf55db1c35210d -->",
  "summary": {
    "body": "### Fallow audit\n\n3 inline findings selected for GitHub review.\n\n<!-- fallow-review -->\n\n<!-- fallow-fingerprint:v3: 06bf55db1c35210d -->",
    "fingerprint": "06bf55db1c35210d"
  },
  "comments": [
    {
      "path": "src/utils.ts",
      "line": 42,
      "side": "RIGHT",
      "body": "**error** `fallow/unused-export`: ...\n\n<!-- fallow-fingerprint:v3: 9a8b7c6d5e4f3a2b -->",
      "fingerprint": "9a8b7c6d5e4f3a2b",
      "legacy_fingerprint": "4c1d7e0a9b2f6358"
    },
    {
      "path": "package.json",
      "line": 5,
      "side": "RIGHT",
      "body": "**error** `fallow/unused-dependency`: ...\n\n**warn** `fallow/unused-dev-dependency`: ...\n\n<!-- fallow-fingerprint:v3: merged:37df0011a9d7ac87 -->",
      "fingerprint": "merged:37df0011a9d7ac87"
    }
  ],
  "marker_regex": "^<!-- fallow-fingerprint:v[23]: ((?:[a-z]+:)?[0-9a-f]{16}) -->\\s*$",
  "marker_regex_flags": "m",
  "meta": {
    "schema": "fallow-review-envelope/v3",
    "provider": "github",
    "check_conclusion": "failure"
  }
}

Each entry under comments[] is fully rendered Markdown that you can POST as-is. Each body has a <!-- fallow-fingerprint:v3: <fingerprint> --> marker. This marker is the stable identifier that matches comments across runs. The top-level marker_regex is the canonical pattern to extract it. It matches the current v3 marker and the older v2 marker. Match a captured value against comments[].fingerprint and against comments[].legacy_fingerprint. Run it (with one capture group) against an existing PR or MR comment to get the fingerprint string. Fallow puts the multiline m flag in a separate field, marker_regex_flags, and not as (?m) in the pattern, because JavaScript RegExp rejects standalone inline flag groups. Pass both fields to your regex engine:

const re = new RegExp(env.marker_regex, env.marker_regex_flags);

let re = regex::RegexBuilder::new(&env.marker_regex)
    .multi_line(env.marker_regex_flags.contains('m'))
    .build()?;

The top-level summary: { body, fingerprint } block has the sticky-summary comment. summary.body is byte-identical to the legacy top-level body field, which stays for v1 consumers. Match summary.fingerprint against existing comments to update the sticky summary in place, or create it. One fallow run gives both the summary and the inline comments, so you do not need a second fallow --format pr-comment-{github,gitlab} run.

When more than one finding is on the same path:line (for example, three unused-dependency variants on package.json:5), fallow merges them into one comment. The body has one paragraph for each finding, and the comment has fingerprint = "merged:<16-char hash of sorted constituent fingerprints>". This fingerprint changes when the set of findings changes. So the bundled wrappers (and fallow ci reconcile-review), which read only the primary fingerprint, skip the comment when its content is the same and post it again when the set changes. A comment with one finding keeps the bare 16-hex fingerprint shape.

To update comments in place and keep reviewer reply threads when the content changes, track the identity yourself:

1. Extract the fingerprint with marker_regex.
2. Run fallow again against the new HEAD and compare the findings in each comment.
3. When the findings differ from the existing comment, call the edit endpoint of the provider: PATCH /pulls/comments/{id} on GitHub, or PUT /discussions/.../notes/{note_id} on GitLab.

The bundled fallow scripts do not do this. Only a consumer that needs to keep threads has to handle the extra work: auth scopes, retry semantics, and the 422 error when you edit a resolved thread.

A comment can also have a truncated: bool field. When it is true, fallow cut the body to fit under a conservative 65,536-byte cap. In practice, GitHub PR review comments reject larger bodies. GitLab note bodies accept up to 1,000,000 characters, as the GitLab application limits docs state. A truncated body always has all three of these signals: the typed truncated: true flag, an inline <!-- fallow-truncated --> HTML marker, and a > Body truncated by fallow. blockquote. Fallow keeps the closing fallow-fingerprint marker, so matching across runs still works.

For GitLab, each comment also has a position block with base_sha, start_sha, head_sha, position_type, old_path, new_path, and new_line. These are the fields that the GitLab discussions API expects. For renamed files (when you run fallow with --diff-file or --diff-stdin), old_path is the base-side filename from the rename from and rename to extended headers of the diff. Inline comments on renamed files then attach to the correct line through the GitLab discussion-position API. When the diff has no rename (the usual case), old_path is the head-side path.

Environment variables that feed the envelope

If neither CI_MERGE_REQUEST_DIFF_BASE_SHA nor FALLOW_GITLAB_BASE_SHA is set, the position block has null SHAs. You must then fill them from the diff_refs of the MR before you POST.

Minimal consumer (GitLab)

fallow audit --diff-stdin --format review-gitlab < diff.patch > plan.json

jq -c '.comments[]' plan.json | while read -r comment; do
  curl --silent --request POST \
    --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
    --header "Content-Type: application/json" \
    --data "$comment" \
    "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/discussions"
done

If your runner also has no jq, parse the JSON in the language of your CI (Node, Python, Go) and POST each entry as-is. The shape under comments[].position matches the GitLab discussions API field for field, so you do not need to map fields.

Reconciliation across runs

To prevent duplicate threads on later pushes, fetch the existing MR discussions before you POST, and extract their fingerprints from the marker. The simplest sed extraction matches the marker prefix <!-- fallow-fingerprint:v2: or <!-- fallow-fingerprint:v3: and the fingerprint token. Then compare the results with comments[].fingerprint and comments[].legacy_fingerprint:

existing=$(curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/discussions?per_page=100")

existing_fps=$(echo "$existing" | jq -r '.[].notes[].body? // empty' \
  | sed -n 's|.*fallow-fingerprint:v[23]: \([^ ]*\) .*|\1|p' \
  | sort -u)

# For each comment in plan.json, only POST when neither its fingerprint
# nor its legacy_fingerprint is already present in $existing_fps.

To resolve threads when a finding goes away between runs, use fallow ci reconcile-review --provider gitlab, if you can give fallow a token. If you cannot, use the same fingerprint comparison in your own script. Both paths use the same marker, so they give the same result. The bundled reconciler accepts v1 (<!-- fallow-fingerprint: <hash> -->), v2 (<!-- fallow-fingerprint:v2: <fingerprint> -->) and v3 (<!-- fallow-fingerprint:v3: <fingerprint> -->) markers. After an upgrade, it processes old comments with no extra steps.

Upgrade to v3 markers

Before the v3 marker, the fingerprint of a dead-code comment held the line of the finding. When you added lines above an unused export, the thread resolved and a new thread opened for the same finding. Now the fingerprint comes from the finding_id, and review comments end with <!-- fallow-fingerprint:v3: <fingerprint> -->. Duplication, health and security fingerprints did not change.

When the old line-based value is different, a comment has it in the optional legacy_fingerprint field. For one release, fallow ci post-review and fallow ci reconcile-review match an open thread with a v2 marker through this value:

• They do not post a second thread for the same finding.
• They do not resolve the v2 thread as stale.
• A v2 thread stays open until its finding goes away or its old line-based value changes. The finding then gets one v3 thread, which stays open across line shifts.

The bundled GitHub Action and GitLab template use these commands, so the first run after the upgrade posts no duplicate threads. A script that posts from the envelope itself must match each captured marker value against fingerprint and legacy_fingerprint.

The reconciler stops at the first failed provider change. When a provider target is gone or a change fails, the JSON output keeps the apply_errors array. It can also add apply_hint, failed_fingerprints, and unapplied_fingerprints. CI wrappers and custom integrations can then show a retry hint and know which old findings are still unresolved.

Schema stability

The envelope has the tag meta.schema, for example "fallow-review-envelope/v3". New fields are backwards-compatible, so ignore fields that you do not know. For a dead-code finding, fallow computes the fingerprint from its finding_id, so it stays the same when lines move. For other findings, fallow computes the fingerprint hash from rule_id + path + snippet. In both cases it stays the same when only whitespace or the body Markdown changes. Code written for v1 still works on v2 output, because the v1 top-level body field stays. Code written for v2 should validate the schema marker against ^fallow-review-envelope/v[0-9]+$, so it keeps working when fallow moves to v3.

Duplication checks

- run: npx fallow dupes --threshold 5 --format compact

The job fails when the overall duplication percentage is more than 5%.

To fail the job on any clone group, use --fail-on-issues:

- run: npx fallow dupes --fail-on-issues --format compact

To check duplication only in files that the PR or MR changes, use --changed-since:

- run: npx fallow dupes --changed-since origin/main --format compact

Health checks

- run: npx fallow health --format compact

Reports complexity findings, the health score, file scores, hotspots, and refactoring targets. Circular dependencies lower the health score and can show as refactoring targets. To list each cycle, run fallow architecture --cycles. To change the threshold, use --max-cyclomatic 15.

Fallow works in any CI environment that can run Node.js or install fallow. The commands are the same everywhere:

# Run all analyses (no install needed)
npx fallow --format compact

# Or individual commands
npx fallow dead-code --format compact
npx fallow architecture --format compact
npx fallow dupes --format compact
npx fallow health --format compact

# Or download the binary directly
curl -fsSL https://get.fallow.dev | sh
fallow --format compact

Exit codes

The bare fallow run in a machine format (JSON, SARIF, CodeClimate, the GitHub formats, and the comment and review formats) exits 0 on findings. The human, compact and markdown formats exit 1. With --fail-on-issues or --ci, the bare run exits 1 on error-severity findings in every format. When the run analyzes duplication, it also exits 1 when at least one clone group remains. fallow dupes without a gate flag exits 0. With --fail-on-issues or --ci, it exits 1 when at least one clone group remains.

The action does this with auto-changed-since, which is on by default. To turn it off and run a full analysis on PRs:

- uses: fallow-rs/fallow@v3
  with:
    auto-changed-since: false

To compare against a custom ref in place of the PR base SHA:

- uses: fallow-rs/fallow@v3
  with:
    changed-since: origin/main

The template does this in MR pipelines. To use a custom ref:

fallow:
  extends: .fallow
  variables:
    FALLOW_CHANGED_SINCE: "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"

- run: npx fallow --changed-since origin/main

- uses: fallow-rs/fallow@v3
  with:
    command: audit
    gate: new-only        # default; fails only on findings introduced by this PR
    fail-on-issues: true

The action has the outputs outputs.verdict (pass, warn, or fail) and outputs.gate, so later steps can act on the verdict:

- uses: fallow-rs/fallow@v3
  id: fallow
  with:
    command: audit

- name: Block release on regression
  if: steps.fallow.outputs.verdict == 'fail'
  run: exit 1

fallow:
  extends: .fallow
  variables:
    FALLOW_COMMAND: "audit"
    FALLOW_AUDIT_GATE: "new-only"
    FALLOW_FAIL_ON_ISSUES: "true"

npx fallow audit --base origin/main --gate new-only --quiet

Exits 0 on pass or warn, and 1 on fail.

The action sets three outputs on every run, also when nothing failed. Each output has a default value, so a later if: can match on a value (== 'false' or == 'none') and does not have to tell an absent output from false:

- uses: fallow-rs/fallow@v3
  id: fallow

- name: Alert on degraded scoping
  if: steps.fallow.outputs.changed-files-unavailable == 'true'
  run: echo "::warning::Fallow ran unscoped; PR scoping disabled by API failure"

- name: Alert on dedup degradation
  if: steps.fallow.outputs.dedup-lookup-failed == 'true'
  run: echo "::warning::Fallow PR comments may be duplicated"

A 4xx response (auth, scope, or permission error) on the multi-comment review path causes exit 1 and fails the action step, because a new run cannot fix a configuration error. 5xx responses, 429s after all retries, and network errors return exit 0 with the warning, so a temporary problem does not break PRs.

comment.sh and review.sh write two sidecar artifacts with the same signals. The template lists both in artifacts: paths:, so later jobs can read them:

alert-degraded-fallow:
  stage: notify
  needs: [fallow]
  script: |
    if [ "$(cat fallow-skip-reason.txt)" = "pagination_failure" ]; then
      echo "WARNING: Fallow inline review skipped to avoid duplicates"
    fi
    if [ "$(cat fallow-dedup-lookup-failed.txt)" = "true" ]; then
      echo "WARNING: Fallow MR comments may be duplicated; re-run the fallow job"
    fi

A 4xx response on the multi-discussion review path returns exit 1, but the bash review.sh || echo "WARNING: ..." line in the template hides it. To fail CI on an auth misconfiguration, remove the || echo from your template, or gate on the sidecar files.