gha-command-proof

gha-command-proof validates the GitHub Actions runner command protocol without needing GitHub. It parses workflow commands written to stdout/stderr, validates environment files such as GITHUB_ENV and GITHUB_OUTPUT, redacts registered masks, and emits a text, JSON, or Markdown receipt.

It is built for offline CI runners, action authors, and tools like ci-forge that need to explain whether a local run behaved like a GitHub runner would.

Install

cargo install gha-command-proof --locked

Use

Validate a command stream:

gha-command-proof log .\examples\logs\good.log

Validate an environment file:

gha-command-proof env-file --kind env .\examples\env\GITHUB_ENV
gha-command-proof env-file --kind output .\examples\env\GITHUB_OUTPUT

Validate a whole step boundary:

gha-command-proof step `
  --log .\examples\logs\good.log `
  --github-env .\examples\env\GITHUB_ENV `
  --github-output .\examples\env\GITHUB_OUTPUT

Write JSON or Markdown receipts:

gha-command-proof log .\examples\logs\good.log --format json --output receipt.json
gha-command-proof step --log .\examples\logs\good.log --format markdown --output receipt.md

Write a redacted copy of the log:

gha-command-proof log .\examples\logs\good.log --redacted-log-output redacted.log

What It Checks

• Modern ::command key=value::data workflow commands.
• Legacy ##[command key=value]data workflow commands still parsed by GitHub runners.
• Runner escape mappings for command data and properties.
• add-mask redaction, including multiline and whitespace-separated mask candidates.
• stop-commands suppression and resume-token validation.
• Annotation commands: notice, warning, and error.
• Group balance for group / endgroup.
• Disabled commands: set-env and add-path.
• Deprecated commands: set-output and save-state.
• GITHUB_ENV, GITHUB_OUTPUT, and GITHUB_STATE assignment and heredoc syntax.
• GITHUB_ENV restrictions for NODE_OPTIONS and default runner variables.
• GITHUB_OUTPUT values that were previously registered with add-mask.
• GITHUB_PATH path records.
• GITHUB_STEP_SUMMARY size limit and redacted summary content.

GitHub Actions

jobs:
  gha-command-proof:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: wildmason/gha-command-proof@v1
        with:
          mode: step
          log: step.log
          github-output: github-output.txt
          format: markdown
          output: gha-command-proof.md

The action wrapper installs the published crate with cargo install. For air-gapped use, install the binary in your runner image and call the CLI directly.

Exit Codes

The CLI exits 0 when there are no failed checks. Warnings do not fail the run unless --strict is passed.

Receipts

Every run emits a receipt with:

• tool name and version
• checked timestamp
• pass/warn/fail/skip summary
• check list with optional source and line
• parsed command records
• parsed environment-file records

Receipt data is designed to be consumed by offline runners and support-bundle tools. Masked values are redacted before they are rendered.

See docs/spec.md for protocol scope and docs/RULES.md for stable check IDs.

Limits

gha-command-proof validates the command channel and file-command protocol. It does not execute workflows, evaluate expressions, resolve actions, run containers, upload artifacts, or emulate GitHub API services.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.