workflow contracts for GitHub Actions

Declare. Capture. Validate.

github-actionspec-rs links three things: the workflow behavior you expect, the workflow payload you observed, and the validation report that explains whether they match.

See the flow README

1. Declare: .cue contract
2. Capture: workflow payload
3. Validate: report and dashboard

mental model local ci

build-infrastructure.yml
  -> .github/actionspec/build-infrastructure/staging.cue
  -> .github/actionspec-artifacts/build-infrastructure.json
  -> target/actionspec/validation-report.json

What This Project Does

It checks that a workflow run behaved the way you said it should.

You define the expected shape of a run in CUE, collect the actual run payload as JSON, then compare both. That is the full model.

What It Is Not

It does not execute your workflow.
It does not replace unit or integration tests.
It does not guess expected behavior for you.

How It Works

The three steps are one chain.

Each step feeds the next one. Step 1 produces the contract. Step 2 produces the payload for the same workflow. Step 3 consumes both and tells you if they match.

Step 1

Declare expected behavior

Write a .cue contract under .github/actionspec.

Produces: the expected contract for one workflow.

package actionspec

workflow: "ci.yml"

run: #Declaration.run & {
  workflow: workflow
  jobs: {
    build: { result: "success" }
  }
}

Step 2

Provide actual behavior

Use a fixture payload, capture fragments into one payload, or capture a real CI run.

Produces: the observed payload for that same workflow.

github-actionspec capture \
  --workflow ci.yml \
  --job-file .github/actionspec-fragments \
  --output .github/actionspec-artifacts/ci-main.json

Step 3

Compare expected vs actual

Validate the payload and render a report or dashboard for humans.

Consumes: the contract from step 1 and the payload from step 2.

just validate-repo-report . ci.yml \
  .github/actionspec-artifacts/**/*.json \
  target/actionspec/validation-report.json

Why Use It

Make workflow behavior reviewable.

Catch workflow drift before it breaks automation.
Lint reusable workflow interfaces with validate-callers.
Use the same validation model locally and in CI.

Review behavior changes through reports instead of reading logs by hand.
Diff the current matrix against a baseline artifact in PRs.
Validate real CI runs on protected branches once the flow is stable.

Where It Runs

Same model, different delivery.

CLI

Local validation

Use just lint, just test, and just validate-repo-report.

GitHub Action

Workflow integration

Run emit, capture, and validate flows inside GitHub Actions with the bundled runtime.

Runtime image

Automation-friendly

Use the published runtime image when you want the CLI plus cue bundled together.

Start Small

Start with one workflow and one payload.

The shortest path is: bootstrap one contract from one workflow, validate one payload locally, then wire the same flow into CI once the model is clear.

Open getting started Open troubleshooting