github-actionspec-rs

Workflow Flow

How the validation model works.

This project does not execute workflows. It validates a normalized description of a workflow run against a contract you declared in CUE.

In one line

expected workflow behavior
vs
actual workflow run payload

Important

  • The tool validates payloads. It does not run the workflow for you.
  • The payload can come from fixtures, local capture, or CI capture.
  • The contract stays in the repository next to the workflow it describes.

Capture

Build a normalized payload from job fragments.

The normalized payload is the contract boundary. It is the same shape whether it comes from fixtures, a local capture flow, or a CI run.

Emit one fragment per job

github-actionspec emit-fragment \
  --job build \
  --result success \
  --output contract_build=build-ts-service \
  --matrix app=build-ts-service \
  --file .github/actionspec-fragments/build.json

Capture them into one payload

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

Validation

Use the right mode for the right job.

`validate-callers`

  • Checks local reusable workflow interfaces.
  • Validates required inputs and secrets.
  • Validates obvious literal type mismatches.
  • Checks needs.*.outputs.* references.

`validate-repo`

  • Resolves one declaration from the repo.
  • Validates one or more normalized payloads.
  • Accepts files, directories, globs, and newline-separated lists.
  • Produces a JSON report and optional dashboard.

`dashboard`

  • Renders a markdown matrix from a report.
  • Can diff against a baseline report.
  • Can filter rendered job outputs by key.
  • Fits well in PR comments and uploaded artifacts.

Action usage

Use the same flow in GitHub Actions.

Capture mode

- uses: v4lproik/github-actionspec-rs@main
  id: actionspec-capture
  with:
    mode: capture
    workflow: ci.yml
    ref-name: main
    capture-job-files: |
      ${{ steps.build.outputs.fragment-path }}
      ${{ steps.tests.outputs.fragment-path }}
    capture-file: /github/runner_temp/actionspec/workflow-run.json

Validate mode

- uses: v4lproik/github-actionspec-rs@main
  with:
    repo: .
    workflow: ci.yml
    actual: ${{ steps.actionspec-capture.outputs.capture-path }}
    report-file: /github/runner_temp/actionspec/report.json
    dashboard-file: /github/runner_temp/actionspec/dashboard.md