CI usage
Run flowpact on every pull request that touches workflows, fail on errors and contract drift, and keep the report.
The flowpact action
The simplest setup is the flowpact GitHub Action. It runs the same engine as the CLI and adds a job summary, inline annotations on the pull request and — when contracts drifted — the regenerated contracts as a downloadable artifact.
name: Workflow contracts
on:
pull_request:
paths:
- '.github/workflows/**'
- '.github/actions/**'
- '.github/flowpact/**'
permissions:
contents: read
jobs:
flowpact:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: rumankazi/flowpact@v0.5
with:
mode: check # or lint, if you do not commit contractsSee GitHub Action for every input and output (fail-on, SARIF upload, the contracts artifact, …).
The CLI in GitHub Actions
The CLI works in any job that has Node.js:
name: Workflow contracts
on:
pull_request:
paths:
- '.github/workflows/**'
- '.github/actions/**'
- '.github/flowpact/**'
permissions:
contents: read
jobs:
flowpact:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Check workflows and contracts
run: npx --yes flowpact check --output flowpact-report.md --patch flowpact-contracts.patch
- name: Job summary
if: always()
run: cat flowpact-report.md >> "$GITHUB_STEP_SUMMARY"
- name: Keep the regenerated contracts
if: always()
uses: actions/upload-artifact@v7
with:
name: flowpact-contracts
path: flowpact-contracts.patch
if-no-files-found: ignore- Use
flowpact lintinstead offlowpact checkif you do not commit contracts. --output flowpact-report.mdwrites a Markdown report (format by extension), which the next step appends to the job summary. Use.jsonfor a machine-readable report instead.- The step fails (exit
1) when there are errors, which inflowpact checkincludes missing, outdated, breaking, orphaned and invalid contracts. Use--fail-on warningto be stricter or--fail-on neverto report without failing. --patchwritesflowpact-contracts.patchonly when contracts drifted. Anyone can download it from the run and apply it withgit apply flowpact-contracts.patch— no local Node.js needed.- The terminal output in the job log is the same as locally (colors are kept in GitHub's log viewer).
- When you re-run a job with debug logging enabled, GitHub sets
RUNNER_DEBUG=1and flowpact switches to debug logs automatically.
Code scanning (SARIF)
To see findings in the Security → Code scanning tab and as pull request annotations, write SARIF and upload it:
permissions:
contents: read
security-events: write
steps:
# …checkout and setup-node as above
- run: npx --yes flowpact check --output flowpact.sarif
- if: always()
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: flowpact.sarif
category: flowpactPin the version
npx --yes flowpact@0.5 checkThe banner at the top of the log shows the exact tool and schema versions that produced the result.
Other CI systems
flowpact only needs Node.js and the repository files:
npx --yes flowpact check --format json --output flowpact-report.json --patch flowpact-contracts.patch