10 min read

GitHub Action

The StateAnchor GitHub Action (stateanchor-hq/sync-action@v1) gates every API spec change in CI. On each push it diffs your stateanchor.yaml against the prior IR snapshot and blocks breaking changes (ERR lane), warns on degradations (WARN lane), and passes additive changes (INFO lane). Every gate decision is written to an append-only Merkle audit log.

Overview

On each triggering event the action performs three steps in sequence:

1. OIDC exchange -- requests a GitHub OIDC token and exchanges it with StateAnchor for a short-lived action token. This authenticates the repo without storing secrets in your repository settings.
2. Validate -- sends stateanchor.yaml to /api/action/validate for schema and structural validation.
3. Gate check -- calls /api/action/gate-check to diff the spec against the previous IR, classify breaking changes into ERR / WARN / INFO lanes, and return a gate decision.

Pull requests from forks cannot receive OIDC tokens. In that case the action automatically runs local YAML validation only and emits a soft-pass -- it never fails-closed on a fork.

Installation

Copy the example workflow below into .github/workflows/stateanchor-gate.yml in your repository. No secrets are required when GitHub OIDC is available.

# StateAnchor -- API Contract Gate
#
# This action gates every API spec change in CI. On each push it diffs your
# stateanchor.yaml against the prior snapshot and blocks breaking changes (ERR),
# warns on degradations (WARN), and passes additive changes (INFO).
#
# Full docs: https://stateanchor.dev/docs/github-action

name: StateAnchor Gate

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  id-token: write   # required for GitHub OIDC authentication to StateAnchor
  contents: read
  pull-requests: write  # required to post gate verdict as a PR comment

jobs:
  stateanchor-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: stateanchor-hq/sync-action@v1
        with:
          # Gate mode: "enforce" runs a full gate check that can block your CI.
          # Use "audit" to adopt StateAnchor without blocking merges while you
          # get familiar with the gate signal.
          mode: enforce

          # Post the gate verdict as a PR annotation and step summary.
          annotate-pr: 'true'

          # Fail the PR step when the gate returns ERR.
          # Set to false for advisory-only adoption (gate reports but does not block).
          enforce-on-prs: 'true'

          # Path to your stateanchor.yaml (default: stateanchor.yaml at repo root).
          # config-path: stateanchor.yaml

Required permissions

The action requires two GitHub permissions in your workflow:

Inputs reference

Outputs reference

Using outputs in your workflow

Reference outputs using the step ID to add conditional downstream steps:

- uses: stateanchor-hq/sync-action@v1
  id: sa
  with:
    mode: enforce

- name: Comment on PR if blocked
  if: steps.sa.outputs.gate-action == 'block'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: ' StateAnchor blocked this PR. Lane: ' +
              '${steps.sa.outputs.gate-result}' + ', Score: ' +
              '${steps.sa.outputs.gate-score}'
      })

- name: Deploy if gate proceeds
  if: steps.sa.outputs.gate-action == 'allow'
  run: echo "Gate passed -- deploying"

Behavior documentation

On a PASS result (gate-action: allow)

When the gate returns allow (lane INFO or WARN below threshold), the action sets result: pass and exits with code 0. CI continues normally. The sync run is recorded in the StateAnchor dashboard and the Merkle log.

On a block result (gate-action: block)

When the gate returns block (lane ERR), the action sets result: fail and exits with code 1, causing the workflow step to fail. The Actions log includes the block reason, effective score, a table of breaking operations, and the sync run ID for dashboard lookup. Whether the PR check fails depends on enforce-on-prs -- set it to false to log the block without preventing merge during advisory adoption.

When StateAnchor is unreachable (fail-open)

When outage-policy: fail-open is set and the API is unreachable, the action runs local YAML schema validation (if local-fallback: true) and emits result: soft-pass. No breaking-change diff was evaluated -- treat soft-pass as "the spec parsed but the gate was unreachable" and review the sync manually before deploying. This is consistent with ADR-004: StateAnchor never blocks customer CI on its own downtime.

Rate limiting (429 / 503)

When the gate-check endpoint returns 429 or 503, the action reads the Retry-After response header (defaulting to 30 seconds if absent), waits that duration, and retries the request once. If the retry also fails, the action falls through to the outage handler -- fail-open proceeds with soft-pass, fail-closed fails the step.

Fork PR behavior

Fork pull requests do not receive workflow secrets or GitHub OIDC tokens. The action detects this automatically by reading the GITHUB_EVENT_PATH payload. It then:

• Emits a workflow-level warning identifying local-validation mode.
• Runs local YAML schema validation.
• Always emits result: soft-pass if validation passes -- it never fails-closed on a fork.
• Does not post PR annotations (cannot authenticate to the base repo).

How the OIDC token exchange works

StateAnchor uses GitHub's native OIDC provider to authenticate Actions without long-lived secrets -- the same mechanism used by AWS, GCP, and Azure for keyless auth from GitHub Actions.

1. The action requests a short-lived JWT from GitHub's OIDC provider using the id-token: write permission. This token is scoped to the current workflow run and expires in minutes.
2. The action sends this JWT to POST /api/action/oidc/exchange on the StateAnchor API, along with the repository, ref, SHA, workflow, and job fields.
3. StateAnchor validates the JWT signature against GitHub's OIDC JWKS endpoint, checks the repository, ref, and workflow claims, and verifies the repository is linked to a StateAnchor project.
4. If valid, StateAnchor returns a single-use action token with a 5-minute TTL and a unique JTI (JWT ID) that prevents replay attacks.
5. The action uses this token for all subsequent API calls. After use, the JTI is recorded and the token cannot be reused.

The GitHub OIDC token is validated and discarded immediately -- it is never stored. No API keys or secrets are required in your repository settings.

Multi-environment configuration

For teams with staging and production environments, use separate workflow files or conditional inputs:

# .github/workflows/stateanchor-staging.yml
name: StateAnchor Staging
on:
  push:
    branches: [develop]
permissions:
  id-token: write
  contents: read
jobs:
  stateanchor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: stateanchor-hq/sync-action@v1
        with:
          mode: audit          # staging: report only, never block
          config-path: stateanchor.yaml

# .github/workflows/stateanchor-prod.yml
name: StateAnchor Production
on:
  push:
    branches: [main]
permissions:
  id-token: write
  contents: read
jobs:
  stateanchor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: stateanchor-hq/sync-action@v1
        with:
          mode: enforce        # production: block breaking changes
          outage-policy: fail-open
          config-path: stateanchor.yaml

What the Action logs look like

Successful run (gate: INFO, action: allow)

[StateAnchor] OIDC exchange: success (token expires in 300s)
[StateAnchor] Validating stateanchor.yaml...
[StateAnchor] Validation: pass (4 endpoints, 2 models)
[StateAnchor] Gate check: running...
[StateAnchor] Gate result: allow (score: 0)
  Lane: INFO
  No breaking operations detected
[StateAnchor] Sync run: fb87c28a-4509-4c7b-b3e1-... (completed)
[StateAnchor] ok Done -- result: pass

Blocked run (gate lane: ERR, action: block)

[StateAnchor] OIDC exchange: success (token expires in 300s)
[StateAnchor] Validating stateanchor.yaml...
[StateAnchor] Validation: pass (3 endpoints, 2 models)
[StateAnchor] Gate check: running...
[StateAnchor] Gate result: block (score: 65)
  Lane: ERR
  Breaking operations:
    [40] REMOVED endpoint DELETE /users/:id
    [30] REMOVED required field user.email
  Block reason: BLOCK -- breaking removal detected
[StateAnchor] Sync run: a1b2c3d4-... (blocked)
[StateAnchor] x Gate BLOCKED -- exit code 1

Outage with fail-open

[StateAnchor] OIDC exchange: success
[StateAnchor] Validating stateanchor.yaml...
[StateAnchor] Remote validation: failed (timeout after 15000ms)
[StateAnchor] Outage policy: fail-open
[StateAnchor] Local fallback: running YAML schema validation...
[StateAnchor] Local validation: pass
[StateAnchor] ok Done -- result: soft-pass (remote unavailable)

soft-pass explained

soft-pass is not a gate lane -- it is the Action result when the remote gate check could not run and outage-policy: fail-open is configured, or when the action is running on a fork PR. The Action falls back to local YAML schema validation only, and if that passes, emits result: soft-pass. No breaking-change diff was evaluated, no ERR / WARN / INFO lane was assigned, and no artifacts were generated. Treat soft-pass as “the spec parsed but the gate was unreachable” — review the sync manually before deploying.

Troubleshooting

1. “repo_not_linked” error

The repository is not connected to a StateAnchor project. Go to the StateAnchor dashboard, click Connect repository, and follow the GitHub App installation flow. The OIDC exchange will fail until the repo is linked.

2. “invalid_action_token” -- OIDC permissions missing

The action could not obtain a GitHub OIDC token. Verify that your workflow includes:

permissions:
  id-token: write
  contents: read

This block must appear at the workflow level or on the specific job, not just on individual steps. Fork PRs cannot obtain OIDC tokens -- the action falls back to local validation automatically for forks.

3. Gate always passes even on breaking changes

If the gate returns INFO on every push regardless of what you change, check the following:

• stateanchor.yaml is not being read: Verify the file exists at the path specified in config-path (default: stateanchor.yaml at repo root). Check for typos -- the file must be .yaml, not .yml.
• First sync has no prior IR: The very first sync run for a new project has nothing to diff against, so it always passes. Run one sync, then make a breaking change to see the gate block.
• mode: audit: In audit mode the gate runs but never blocks. Switch to mode: enforce to enable blocking.

4. Action fails with 401 on fork PRs

This is expected behavior -- fork PRs cannot receive OIDC tokens and cannot authenticate to StateAnchor. The action should automatically detect the fork context and fall back to local validation. If you are seeing a hard 401 failure instead of local fallback, verify that local-fallback is not set to false.

5. Action is slow (>30 seconds)

The sync pipeline runs five stages: OIDC exchange → spec validation → Stage A IR normalization → Stage B ICE ensemble (3 Haiku evaluators) → Stage C artifact generation. Expected timing under normal load is 8-20 seconds total. If the action consistently exceeds 30 seconds:

• Increase timeout-ms to 20000.
• Check stateanchor.dev for service status -- high latency usually correlates with upstream LLM provider load.
• Consider setting outage-policy: fail-open so timeouts do not block your CI during peak periods.