Documentation

GitHub Action

The composite action runs the CLI in your own CI, with your own credentials for the judge. Use it when you want verification without the hosted app, or alongside it.

Composite action that runs byspec verify in CI, writes the report to $GITHUB_STEP_SUMMARY, uploads byspec-report.json and .byspec/evidence/ as an artifact, and fails the job with the CLI's exit code.

Checkout is your job. Run actions/checkout first; use fetch-depth: 0 so --changed can find the merge base.

yaml

jobs:
  byspec:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # for the OIDC role below
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_BYSPEC_ROLE_ARN }}
          aws-region: us-east-1
      - uses: adamchensley/byspec/action@main
        with:
          spec: specs/product.spec.md
          fail-on-unverifiable: "true"

Source: action/README.md § Byspec GitHub Action

Inputs#

Input	Default	Meaning
`spec`	`""`	Spec file(s), space-separated. Empty means `config.spec_globs`.
`changed`	`"true"`	Adds `--changed`: only criteria touched by the diff.
`provider`	`"bedrock"`	`bedrock`, `anthropic`, or `mock`.
`fail-on-unverifiable`	`"false"`	Adds `--fail-on-unverifiable` (exit 2 on any UNVERIFIABLE).
`frozen-spec`	`"true"`	Adds `--frozen-spec`: a spec file in the diff fails the run.
`no-judge`	`"false"`	Adds `--no-judge`: never call the model.
`node-version`	`"22"`	Node.js version.
`version`	`"latest"`	npm version of `@byspec-dev/cli` to install.
`working-directory`	`"."`	The repository root passed to the CLI.
`local`	`"false"`	Build and run the CLI from this checkout instead of npm (what Byspec's own workflows use).

Source: action/README.md § Inputs

Outputs#

Output	Meaning
`exit-code`	`0` ok, `1` FAIL, `2` UNVERIFIABLE, `3` config/spec error, `4` provider error.
`report`	Path of the JSON run report.

Source: action/README.md § Outputs

Credentials#

The action never reads credentials from config. For the Bedrock judge, configure AWS credentials in your workflow before this action; the recommended way is an OIDC role via aws-actions/configure-aws-credentials. For the Anthropic API, set ANTHROPIC_API_KEY in env and pass provider: anthropic. The mock provider needs nothing and is what Byspec's required dogfood check uses.

Until @byspec-dev/cli is published to npm, set local: "true" in a checkout of this repository, or build it yourself (pnpm install && pnpm build) and call pnpm byspec verify … directly.

Source: action/README.md § Credentials