flowpact

Introduction

flowpact finds what gets lost between GitHub Actions workflows — missing inputs, dead outputs, inherited secrets and matrix legs that silently run with empty values.

Large CI setups grow into a tree: one pipeline.yml with dozens (or hundreds) of workflow_call inputs fans out to reusable workflows, which call more reusable workflows and composite actions. Each level passes a different subset of values down and hands outputs back up. Eventually nobody can answer:

  • Where does this input actually go?
  • Is anything we pass ignored, or anything we read never passed?
  • Does every matrix leg get every value it needs?

GitHub does not help: a missing matrix key, an undeclared secret or an optional input without a default all evaluate to an empty string — no error, no warning, a green run.

flowpact lint reporting FP401: input config is empty for the windows matrix combination
The real incident that motivated flowpact: one matrix entry had no config, so that test variant never ran.

What flowpact does

flowpact parses your workflows and local actions into a data-flow graph — every input, secret, env var, matrix key and output, where it is defined and where it is read, across every level of nesting — and runs rules over it.

Lint

51 rules with stable codes, exact locations, the call chain, why it matters, how to fix it and a docs link.

Contracts

A generated lockfile per workflow and action. flowpact check fails on drift and marks breaking interface changes.

Trace and graph

Follow any input, secret or output down to where it is used or up to where it comes from; draw the call graph.

Impact mode

For publishers of workflows and actions: with impact mode on, a pull request fails when its changes need a minor or major release and it declares less, such as a renamed check declared as a patch.

GitHub Action

Job summary, pull request annotations and regenerated contracts as a downloadable patch.

Configure

Severities, overrides with a reason and an expiry date, runtime matrix shapes and plugin rules.

Quick start

npx flowpact lint       # find problems
npx flowpact generate   # lock the interfaces in .github/flowpact/
npx flowpact check      # lint + fail when the workflows no longer match the contracts

Run it at the root of a repository. See Getting started for installation options and how to read the output.

Getting started

Install flowpact, run your first lint and read the output.

On this page

What flowpact doesQuick start