GitHub Action

The flowpact action (GitHub Marketplace) runs the same engine as the CLI, bundled into the action itself, so the job does not need Node.js or a package install. On top of the CLI's checks it:

• annotates every finding on the file and line it is about, in the run and in the pull request diff;
• writes a job summary with the findings, their fixes and links to the rule docs;
• writes JSON, SARIF or Markdown reports for other steps (for example code scanning);
• in check mode, when contracts drifted, uploads the regenerated contracts and a patch as an artifact, so anyone can update them without running flowpact.

UsageCopy Anchor Link

Lint workflows on pull requestsCopy Anchor Link

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

The step fails when there are errors. Use fail-on: warning to be stricter or fail-on: never to report without failing.

Check contracts and hand out the fixCopy Anchor Link

Once you commit contracts (flowpact generate, see Contracts), use mode: check. It runs every lint rule and also fails when the contracts no longer match the workflows:

    steps:
      - uses: actions/checkout@v7
      - uses: rumankazi/flowpact@v0.5
        with:
          mode: check

When contracts drifted, the action uploads a flowpact-contracts artifact with a patch, and the job summary says how to apply it (see Contract drift without the CLI).

Upload findings to code scanning (SARIF)Copy Anchor Link

jobs:
  flowpact:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v7
      - uses: rumankazi/flowpact@v0.5
        with:
          report-sarif: flowpact.sarif
      - if: always()
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: flowpact.sarif
          category: flowpact

if: always() uploads the report even when the flowpact step failed because of findings. Findings then appear under Security → Code scanning. Findings accepted by an override are left out: code scanning has no way to mark them as accepted and would open an alert for each. The JSON report lists them under suppressed.

Use the outputsCopy Anchor Link

      - id: flowpact
        uses: rumankazi/flowpact@v0.5
        with:
          mode: check
          fail-on: never
      - if: steps.flowpact.outputs.breaking != '0'
        run: echo "::warning::${{ steps.flowpact.outputs.breaking }} breaking contract change(s)"

InputsCopy Anchor Link

All inputs are optional.

Even when paths limits the report to some files, flowpact reads every workflow and local action, because findings depend on the callers and callees.

OutputsCopy Anchor Link

AnnotationsCopy Anchor Link

Each finding becomes an error, warning or notice annotation (matching its severity) on the file and line it is about. The title is the rule code and name, and the message ends with the suggested fix and a link to the rule's docs page. With working-directory, file paths are adjusted so annotations land on the right files in the repository.

GitHub limits how many annotations a single step can show. The job summary lists the first max-findings findings (raise it if needed); the SARIF and JSON reports list every finding, so use those when a run has many.

Job summaryCopy Anchor Link

The summary has:

• the tool and schema versions and how long the analysis took;
• a status line and a table of counts (errors, warnings, info, suppressed, workflows, actions, jobs, matrix combinations);
• the findings, errors first, each with its rule docs link, its location (linked to the file at the commit being checked), the affected matrix combinations, and a collapsed Why / fix section with the related locations;
• in check mode, a Contracts section: which contract files are new, changed or removed, every change (breaking ones in bold) and how to apply the regenerated contracts;
• when impact mode ran, an Impact section: the impact the changes require, the declared impact and whether it covers them, with every graded change;
• the findings accepted by overrides, in a collapsed table with each override's reason, expiry and owner;
• with summary-graph: true, the call graph between workflows and local actions as a Mermaid diagram.

After max-findings findings, the rest are only counted. This is the summary for a repository where one matrix leg passes an empty input to a reusable workflow (the incident-matrix fixture in the flowpact repository). In a run, the locations are links:

## flowpact lint

<sub>flowpact v0.5.0 · config schema v1 · contract schema v1 · report schema v1 · 24 ms</sub>

❌ **1 error**

| Errors | Warnings | Info | Suppressed | Workflows | Actions | Jobs | Matrix combinations |
| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 0 | 0 | 0 | 3 | 0 | 3 | 3 |

### ❌ Errors (1)

**[`FP401`](https://rumankazi.github.io/flowpact/docs/rules/fp401) empty-binding-for-matrix-combo** · `.github/workflows/tests.yml:23:19`

Input "config" for .github/workflows/run-suite.yml is empty in 1 of 3 matrix combinations — matrix.config is not defined there

Matrix: `{ name: windows }`

<details><summary>Why / fix</summary>

**Why:** GitHub evaluates a missing matrix key to an empty string — no error, no warning. The affected matrix leg runs with an empty input, so the callee may skip its real work (e.g. a test configuration) while the run stays green.

**Fix:** Set `config` in every combination, or use a fallback: `${{ matrix.config || '<default>' }}`.

**Related locations:**

- `.github/workflows/pipeline.yml:9:11` — jobs.tests calls .github/workflows/tests.yml
- `.github/workflows/tests.yml:18:13` — this include entry has no `config`
- `.github/workflows/run-suite.yml:11:7` — receives the empty value: input "config"

</details>

report-markdown writes the same Markdown to a file, for example to post it as a pull request comment with another action.

Contract drift without the CLICopy Anchor Link

In check mode, when the contracts drifted, the action writes:

• flowpact-contracts.patch: a patch, relative to the repository root, that creates, updates and deletes the contract files;
• flowpact-contracts/README.md: how to apply it;
• flowpact-contracts/<contract files>: the regenerated contracts, for reference (removed contracts are only in the patch).

With upload-contracts: true (the default) these are uploaded as the flowpact-contracts artifact (artifact-name), kept for retention-days days. The artifact holds only the patch and the flowpact-contracts/ folder, so downloading it into the repository does not overwrite any file. To update the contracts without Node.js or flowpact:

gh run download <run-id> -n flowpact-contracts

git apply --index flowpact-contracts.patch   # --index also stages new contract files
rm -r flowpact-contracts.patch flowpact-contracts
git commit -m "Update workflow contracts"

The patch output holds the path of the patch on the runner, if a later step wants to use it (for example to push a commit). If the upload fails, the action logs a warning and goes on; the job summary then suggests flowpact generate.

Monorepos and subdirectoriesCopy Anchor Link

working-directory points flowpact at a folder that holds its own .github directory. Annotations, SARIF locations, the summary's links and the paths in the contract patch are all rewritten relative to the repository root, so they still point at the right files. paths and config are relative to working-directory; the report paths are relative to the workspace.

Each step stages its drift artifact in its own folder and, unless artifact-name is set, names it after working-directory, so several flowpact steps in one job do not overwrite each other. Artifact names must be unique within a run: in a matrix over projects, set artifact-name from the matrix (for example flowpact-contracts-${{ matrix.project }}).

Debug loggingCopy Anchor Link

The log of the flowpact step starts with a banner (tool and schema versions and the Node.js version), then shows the root, the config file and short progress lines in a collapsible group. These are log lines, not annotations.

For more detail:

• set the debug input to true: flowpact prints its debug logs (config resolution, every file parsed, matrix expansion, timing per rule) as ordinary log lines; or
• re-run the job with debug logging enabled: GitHub turns on step debug logging and flowpact sends the same logs to the debug log. FLOWPACT_DEBUG=1 in the step's env works too (FLOWPACT_DEBUG=trace for even more).

Unexpected errors are reported with a stack trace when debug logging is on.

PermissionsCopy Anchor Link

• contents: read to check out the repository. The action itself does not call the GitHub API.
• Uploading the contract drift artifact needs no extra permission.
• security-events: write on the job that uploads SARIF to code scanning (private repositories also need actions: read for that upload). Pull requests from forks get a read-only token, so the SARIF upload only works for branches in the repository itself.