github-actionspec-rs

Troubleshooting

Read the failure before reading the logs.

The validation report stores typed issues, and the dashboard summarizes them before the matrix. Start from the issue kind, then inspect the payload row that failed.

Fast path

  1. Read the issue summary at the top of the dashboard.
  2. Find the failing payload row.
  3. Check the issue path and the payload file.
  4. Only then fall back to raw CUE stderr.

Useful commands

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

just dashboard-report \
  target/actionspec/validation-report.json \
  target/actionspec/dashboard.md

Issue kinds

Each kind points to a different class of mistake.

value_conflict

  • The contract and payload disagree on a concrete value.
  • Common with job results, promoted outputs, matrix labels, or refs.
  • Check the `expected -> actual` values in the report details.

missing_field

  • The contract requires a field that the payload did not include.
  • Usually means a fragment never emitted an output or step value.
  • Check the issue path to see which job output or field is missing.

unexpected_field

  • The payload includes a field the contract does not allow.
  • Common when the payload shape changed but the declaration did not.
  • Tighten the payload producer or loosen the contract intentionally.

constraint_violation

  • The field exists, but the value still breaks the contract.
  • Common with enums like `success` vs `skipped` or richer output constraints.
  • Check the path, then the contract expression behind that field.

cue_error

  • The parser could not classify the stderr into a stronger issue type.
  • Start with the first non-empty CUE stderr line preserved in the report.
  • These are the cases most worth improving in the library next.

Common causes

Most failures come from one of four places.

  • The contract still reflects the old workflow shape.
  • The fragment producer stopped emitting an expected output.
  • The matrix or promoted output changed but the contract did not.
  • The wrong payload file was validated for the chosen workflow.
  • Use fixture payloads to tighten the contract locally first.
  • Use runtime capture on main when modeled payloads are stable.
  • Keep one contract per workflow and one payload per run variant.
  • Prefer small, explicit CUE constraints over clever derived logic.

Next step

Use the report and dashboard together.

The JSON report is the source of truth. The markdown dashboard is the fast review surface. When a failure is unclear in the dashboard, inspect the corresponding payload path in the report before opening raw logs.