Getting Started in 5 Minutes

StateAnchor is a desired-state control plane for APIs. You commit a stateanchor.yaml spec to Git. On every push, StateAnchor parses it, builds a canonical IR, diffs against the previous state, evaluates breaking changes, and regenerates SDKs and MCP servers. This guide gets your first sync running.

Prerequisites

How the first sync works

When you push a commit that includes stateanchor.yaml, the GitHub Action fires. It requests an OIDC token from GitHub, exchanges it with StateAnchor for a short-lived action token, sends your spec for validation, then calls the gate-check endpoint. If the gate allows, artifacts are generated.

Step 1: Add the GitHub Action

Create .github/workflows/stateanchor-sync.yml in your repository:

name: StateAnchor Sync
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
permissions:
  id-token: write
  contents: read
jobs:
  stateanchor-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: movermon/wrapforge-action@main
        with:
          mode: sync
          config-path: stateanchor.yaml
          api-base-url: https://wrapforge.dev

The id-token: write permission is required for OIDC authentication. Without it, the Action falls back to local validation only.

Step 2: Create stateanchor.yaml

Add this file to your repo root:

service: payments-api
version: "1.0.0"

server:
  base_url: https://api.acme.com/v1

endpoints:
  - name: createCharge
    method: POST
    path: /charges
    description: Create a new charge
    auth: bearer

  - name: getCharge
    method: GET
    path: /charges/{id}
    description: Get charge by ID
    auth: bearer

  - name: listCharges
    method: GET
    path: /charges
    description: List all charges
    auth: bearer

outputs:
  typescript: true
  python: true
  mcp: true

Step 3: Push and verify

Commit both files and push to main.

git add .github/workflows/stateanchor-sync.yml stateanchor.yaml
git commit -m "feat: add StateAnchor sync"
git push origin main

Check the Actions tab in GitHub. You should see the StateAnchor Sync workflow running. The summary will show validation result and gate decision.

Step 4: View artifacts

After the sync completes, open your project in StateAnchor. The latest sync run shows generated artifacts: TypeScript SDK, Python SDK, and MCP server. Each artifact is versioned and tied to the exact commit SHA.

Troubleshooting

Action shows SOFT-PASS instead of PASS

OIDC token unavailable, usually a fork PR or missing id-token permission.

Gate returned block

Breaking change detected. Check diff_summary in the action output.

No sync run created

Repo may not be connected in the StateAnchor dashboard.

YAML parse error

Check indentation. Use 2-space indent, no tabs.

Token exchange failed

Check that api-base-url is correct and the repo is connected.