Getting Started

Quick Start

StateAnchor gates API changes in your CI pipeline. Choose how you want to use it, then follow the three-step setup.

Choose your mode

Both modes start free -- 3 gate credits on signup, no credit card required.

Step 1 -- Commit your stateanchor.yaml

Create stateanchor.yaml in your repo root. This file is the sole source of truth for the gate.

service: my-api
version: "1"

info:
  title: My API
  description: Short description of your service

server:
  base_url: https://api.example.com
  auth:
    type: bearer

# Full pipeline only -- add SDK generation:
# outputs:
#   languages: [typescript, python]
#   mcp: true

Not sure what to put here? Use the YAML Scaffolder →

Step 2 -- Add the GitHub Action

Create .github/workflows/stateanchor.yml. Copy this exactly:

# 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).
#
# Get your API key: https://stateanchor.dev/dashboard
# 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:
          # Your StateAnchor API key from https://stateanchor.dev/dashboard
          # Add it as a repository secret: Settings → Secrets → Actions → STATEANCHOR_API_KEY
          # (Not required when GitHub OIDC is available -- the action authenticates automatically.)
          # api-key: ${{ secrets.STATEANCHOR_API_KEY }}

          # 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

The action uses GitHub OIDC for authentication -- no API key secret needed in most cases. See GitHub Action reference for all options.

Step 3 -- Connect your repo

Go to stateanchor.dev, sign in, and connect your repo. StateAnchor will sync automatically on your next push.

→ Connect a repo

What happens next

On your first push, StateAnchor runs the gate. If your spec passes, you’ll see a green check in your PR. If it finds drift, it blocks the merge and tells you exactly what changed.

If the gate blocks your PR, see Handling a block for next steps. The full list of shipped features is in the changelog.

Related

• stateanchor.yaml reference -- full spec for all fields and options
• Gate classification -- how ERR / WARN / INFO verdicts are assigned
• Handling a block -- what to do when the gate returns ERR
• Drift exceptions -- suppressing a specific finding for an intentional breaking change