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-latest
       steps:
         - uses: actions/checkout@v4
         - uses: fallow-rs/fallow@v3
           with:
             format: sarif

   This runs all analyses (dead code + duplication + complexity) by default. Use the command input to run a specific analysis.

   [NOTE]

   When you enable comment: true or review-comments: true, grant the job contents: read, id-token: write, pull-requests: write, and checks: write. The identity permission lets the Action obtain a short-lived Fallow GitHub App token, so feedback is authored by fallow-cloud[bot]. Without id-token: write, analysis and posting continue with github-actions[bot].

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

2. 2

   Configure inputs

   Customize the action with these inputs:

   Input	Default	Description
   command	-- (all)	Command to run (dead-code, dupes, health, audit, security, fix, or empty for all). Legacy alias: check = dead-code.
   root	.	Project root directory
   config	--	Path to config file (.fallowrc.json, .fallowrc.jsonc, fallow.toml, or .fallow.toml)
   format	sarif	Output format
   production	false	Enable 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 if issues are found
   changed-since	--	Only check files changed since this ref
   auto-changed-since	true	Automatically scope to changed files in PR context using base SHA. Ignored when changed-since is set.
   baseline	--	Path to baseline file for comparison. Rejected with exit 2 when command: audit; use dead-code-baseline / health-baseline / dupes-baseline instead.
   save-baseline	--	Save current results as a baseline file. Rejected with exit 2 when command: audit (audit runs three analyses with incompatible baseline formats).
   version	--	Fallow version override. When omitted, the action uses the project package.json fallow dependency spec if present, otherwise latest. The Action ref and the fallow CLI version are independent: uses: fallow-rs/fallow@v3 selects the Action wrapper code only, while the installed CLI resolves from this input, then the project package.json fallow dependency, then latest.
   workspace	--	Scope output to one or more workspaces (exact names, globs, ! negation; comma-separated)
   changed-workspaces	--	Git-derived monorepo scoping: scope to workspaces containing any file changed since REF (e.g. origin/main). Requires fetch-depth: 0. Mutually exclusive with workspace. A missing ref is a hard error (exit 2) rather than silent full-scope fallback.
   comment	false	Post results as a PR comment
   review-comments	false	Post inline PR review comments with typed review-github output and reconcile resolved threads on later runs
   review-guidance	false	Add collapsed "What to do" guidance blocks to inline PR review comments. Requires review-comments: true
   review-id	--	Stable identifier (1-64 characters, A-Za-z0-9._-) that isolates inline review comments when multiple fallow review jobs target the same pull request. See Isolating parallel review jobs.
   annotations	true	Emit findings as inline PR annotations via workflow commands (no Advanced Security required). On fallow >= 3.4.2 the action renders these natively via fallow report --format github-annotations; older binaries fall back to the bundled jq renderers, and version: latest users flip to the native path silently. 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.
   max-annotations	50	Maximum number of inline annotations to emit. On the native path the cap is applied to the rendered stream (GitHub itself displays at most 10 annotations per type per step).
   github-token	$\{\{ github.token \}\}	GitHub token for PR comments and SARIF upload
   branded-token	true	Use a short-lived Fallow GitHub App token for comments and reviews when the workflow grants id-token: write. Falls back to github-token when unavailable.
   broker-url	https://api.fallow.cloud	Fallow token broker used to exchange the workflow identity for the branded app token.
   dupes-mode	mild	Detection mode for dupes command
   min-tokens	--	Minimum token count for a clone (dupes command)
   min-lines	--	Minimum line count for a clone (dupes command)
   threshold	--	Fail if duplication exceeds this % (dupes command)
   skip-local	false	Only report cross-directory duplicates (dupes command)
   score	false	Compute health score (0-100 with letter grade). Enables the health delta header in PR comments (health and bare command)
   trend	false	Compare current metrics against the most recent saved snapshot. Implies score (health and bare command)
   save-snapshot	--	Save vital signs snapshot for trend tracking. Set to true for default path or provide a custom path (health and bare command)
   type-aware	false	Enable optional project-wide TypeScript semantic evidence. Does not emit compiler diagnostics or generic typed lint findings.
   type-aware-projects	""	Comma-separated tsconfig paths. Empty uses automatic project discovery.
   type-aware-require	best-effort	Use complete to fail when semantic analysis is partial or unavailable, including valid zero-finding runs.
   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 strip from Istanbul file paths before matching (health and audit commands). Use when coverage was generated under a different checkout root in CI / Docker (e.g., /home/runner/work/myapp).
   max-crap	30.0	CRAP score threshold (health and audit commands). Functions meeting or exceeding this score contribute to the verdict.
   gate	new-only	Audit verdict gate. new-only fails only on findings introduced by the changeset; 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 (needs a base ref via changed-since or PR auto-scoping). Gated security failures exit with code 8, and the issues output counts only matching gate candidates. PR comment and review renderers do not support security envelopes yet and are skipped for this command.
   dead-code-baseline / health-baseline / dupes-baseline	--	Per-analysis baseline file paths for the audit command (saved by `fallow dead-code
   args	--	Additional arguments to pass to fallow

3. 3

   Upload SARIF (optional)

   Upload results to GitHub Code Scanning to get inline annotations on the PR diff:

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

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

The action does this automatically via auto-changed-since (enabled by default). To disable and run a full analysis on PRs:

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

To use a custom ref instead of the PR base SHA:

- uses: fallow-rs/fallow@v3
  with:
    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 exposes outputs.verdict (pass/warn/fail) and outputs.gate so downstream steps can branch 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

Three composite-action outputs are emitted on every run, regardless of whether the failure path was taken. Default values let downstream if: gates match positively (== 'false' or == 'none') without an absent-vs-false ambiguity:

- 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, permission errors) on the multi-comment review path escalates to exit 1 and fails the action step, because re-running will not resolve a configuration error. 5xx responses, retry-exhausted 429s, and network errors return exit 0 with the warning so transient blips do not break PRs.