gha-expression-proof 1.0.0

GitHub Actions expression evaluator and receipt generator for offline CI compatibility testing
Documentation

gha-expression-proof

gha-expression-proof evaluates GitHub Actions expressions without needing GitHub. It parses ${{ ... }} expressions, evaluates them against supplied context JSON, and emits text, JSON, or Markdown receipts that offline CI systems can attach to workflow planning and execution evidence.

It is built for local runners, action authors, and tools like ci-forge that need to explain how if:, env:, with:, matrix values, and templates resolved.

Install

cargo install gha-expression-proof --locked

Use

Evaluate an expression against a gha-eventsmith context bundle:

gha-expression-proof eval `
  --expr "github.ref == 'refs/heads/main' && contains(github.event.issue.labels.*.name, 'bug')" `
  --github-context fixtures/push/github-context.json `
  --format json

Evaluate a workflow if: condition with GitHub's implicit success() default:

gha-expression-proof eval `
  --expr "github.ref == 'refs/heads/main'" `
  --github-context fixtures/push/github-context.json `
  --if-condition `
  --job-status success

Render a string containing expression interpolations:

gha-expression-proof template `
  --template 'deploy-${{ github.ref_name }}-${{ github.sha }}' `
  --github-context fixtures/push/github-context.json

Evaluate hashFiles() from a workspace:

gha-expression-proof eval `
  --expr "hashFiles('Cargo.lock') != ''" `
  --workspace .

Load additional contexts:

gha-expression-proof eval `
  --expr "fromJSON(env.timeout) > 5" `
  --context-json 'env={"timeout":"10"}'

Supported Surface

  • Literals: null, booleans, numbers, hex numbers, and single-quoted strings.
  • Operators: !, <, <=, >, >=, ==, !=, &&, ||.
  • Context dereference: github.ref, steps.build.outputs.hash, matrix.os.
  • Index access: github.event.pull_request.labels[0].name.
  • Object filters: github.event.issue.labels.*.name.
  • Functions: contains, startsWith, endsWith, format, join, toJSON, fromJSON, hashFiles, success, failure, cancelled, always, and case.
  • Template interpolation for strings containing one or more ${{ ... }} expressions.
  • JSON, Markdown, or text receipts.

The expression behavior is modeled from GitHub's Actions expression documentation: https://docs.github.com/en/actions/reference/workflows-and-actions/expressions.

GitHub Action

jobs:
  expression-proof:
    runs-on: ubuntu-latest
    steps:
      - uses: wildmason/gha-expression-proof@v1
        with:
          mode: eval
          expr: "github.ref == 'refs/heads/main'"
          github-context: fixtures/push/github-context.json
          format: markdown
          output: expression-proof.md

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

Receipts

Receipts include:

  • tool name and version
  • expression or template input
  • result value, type, string rendering, and truthiness
  • loaded context roots
  • referenced context roots
  • called functions
  • pass/warn/fail/skip summary
  • stable check IDs

Limits

gha-expression-proof is an expression oracle, not a full workflow runner. It does not parse workflow YAML, expand matrices, execute steps, resolve actions, evaluate every runner-side context lifecycle rule, or call GitHub APIs. Object/array equality is modeled by context-origin identity where possible and is intentionally conservative for values created by functions.

See docs/spec.md for compatibility notes and docs/RULES.md for receipt check IDs.

License

Licensed under either of:

at your option.