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.
In VS Code, install the extension from the Visual Studio Marketplace, or from Open VSX in VSCodium, Cursor, Windsurf and other editors built on VS Code. It bundles the language server, so it needs neither Node.js nor the npm package.
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 or uses: $/path points to; a
step's ./path is mapped through the job's actions/checkout steps, since it is relative to the runner's workspace).
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
See findings as you type
Install the extension from the Visual Studio Marketplace or Open VSX. It reports the same findings while you edit, unsaved changes included, and shows on hover where a value comes from and where it goes. Other editors: see editors.
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. If other repositories use your workflows or actions, impact mode also
fails a pull request whose title declares less than the minor or major release its changes need.
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 |