CI usage

The flowpact actionCopy Anchor Link

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: ciatlas/flowpact@v0.12
        with:
          mode: check   # or lint, if you do not commit contracts

See GitHub Action for every input and output (fail-on, SARIF upload, the contracts artifact, …).

The CLI in GitHub ActionsCopy Anchor Link

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 --format github
          -o markdown:"$GITHUB_STEP_SUMMARY"
          --patch flowpact-contracts.patch
      - 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 lint instead of flowpact check if you do not commit contracts.
• --format github annotates each finding on its file and line, in the run and the pull request, like the action. Leave it out to print the terminal report in the job log instead (GitHub's log viewer keeps its colors).
• -o markdown:"$GITHUB_STEP_SUMMARY" writes the Markdown report to the job summary. -o can be repeated, e.g. -o flowpact.sarif for code scanning or -o flowpact-report.json for a machine-readable report.
• The step fails (exit 1) when there are errors, which in flowpact check includes missing, outdated, breaking, orphaned and invalid contracts. Use --fail-on warning to be stricter or --fail-on never to report without failing.
• --patch writes flowpact-contracts.patch only when contracts drifted. Anyone can download it from the run and apply it with git apply flowpact-contracts.patch — no local Node.js needed.
• When you re-run a job with debug logging enabled, GitHub sets RUNNER_DEBUG=1 and flowpact switches to debug logs automatically.

Code scanning (SARIF)Copy Anchor Link

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: flowpact

Pin the versionCopy Anchor Link

npx --yes flowpact@0.12 check

The banner at the top of the log shows the exact tool and schema versions that produced the result.

Other CI systemsCopy Anchor Link

flowpact only needs Node.js and the repository files:

npx --yes flowpact check --format json --output flowpact-report.json --patch flowpact-contracts.patch