Getting started
Install flowpact, run your first lint and read the output.
Install
flowpact needs Node.js 22 or newer. The npm package and the command are both flowpact.
Install once and use flowpact anywhere:
npm install --global flowpact
flowpact lintIn GitHub Actions, use the action instead: it needs neither Node.js nor an install.
First run
Lint the repository
flowpact lintflowpact reads .github/workflows/*.yml and every local action (action.yml under .github/actions/, the
repository's own action.yml at the root, plus any other directory a uses: ./path points to). It always loads the whole repository, because most problems span files.
Read a finding
Each finding shows, top to bottom:
| Part | Meaning |
|---|---|
✖ ERROR FP401 empty-binding-for-matrix-combo | severity, stable code and rule name |
| message | what is wrong, in one sentence |
▶ file:line:col + code frame | exactly where, with the expression underlined |
matrix | the affected matrix combinations (matrix rules only) |
context | related locations — the call chain from the top-level workflow, the include entry, the receiving input |
why / fix | why it matters and what to change |
docs | a link to the rule page (clickable in terminals that support hyperlinks) |
The run ends with a summary card: counts per severity, files, jobs, matrix combinations, graph size and the most frequent codes.
Dig deeper
flowpact explain FP401 # why/fix/examples for a code
flowpact trace pipeline.yml:config # where does this input go?
flowpact trace run-suite.yml:config --up # where does this value come from?Narrow it down
flowpact lint .github/workflows/release.yml # only report on some files (everything is still analyzed)
flowpact lint --only FP401,FP101 # only run some rules
flowpact lint --hide-info # list errors and warnings onlyNext steps
Lock the interfaces
flowpact generate # write .github/flowpact/**/*.contract.yml
git add .github/flowpact && git commit -m "Add workflow contracts"
flowpact check # lint + compare with the committed contractsContracts make every change to an input, secret, output or call visible in review, and flowpact check
fails on breaking changes.
Run it in CI
Add the GitHub Action or the CLI to a workflow — see CI usage.
Tune it
Change severities, accept specific findings with a reason and an expiry date, or add your own rules in the configuration.
Exit codes
| Code | Meaning |
|---|---|
0 | No findings at or above --fail-on (default: error) |
1 | Findings at or above --fail-on (in flowpact check, this includes contract drift) |
2 | Usage or configuration error (unknown rule, invalid config, plugin that fails to load, nothing to analyze) |
3 | Internal error — please report it with --debug output |