Quickstart

Node.js Quickstart

Add StateAnchor to an Express, Fastify, or any Node.js API. You’ll get a gate verdict on every PR in about 5 minutes.

Step 1 -- Add stateanchor.yaml to your repo root

Describe your API endpoints. This file is the gate’s single source of truth -- every push is diffed against the prior snapshot of this file:

service: my-api
version: "1.0.0"

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

endpoints:
  - name: listUsers
    method: GET
    path: /users
    description: List all users

  - name: createUser
    method: POST
    path: /users
    description: Create a new user
    body:
      name: string
      email: string

  - name: getUser
    method: GET
    path: /users/{id}
    description: Get a user by ID
    parameters:
      - name: id
        in: path
        type: string
        required: true

Not sure what to put here? Use the YAML Scaffolder → or read the full stateanchor.yaml reference.

Step 2 -- Add the GitHub Action

Create .github/workflows/stateanchor.yml in your repo:

name: StateAnchor Gate

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

permissions:
  id-token: write   # GitHub OIDC -- no API key secret needed
  contents: read
  pull-requests: write

jobs:
  stateanchor-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: stateanchor-hq/sync-action@v1
        with:
          mode: enforce
          annotate-pr: 'true'
          enforce-on-prs: 'true'

The action authenticates via GitHub OIDC -- no API key or secret required. See the GitHub Action reference for all options.

Step 3 -- Connect your repo at stateanchor.dev

Sign in and connect your GitHub repo. StateAnchor syncs automatically on your next push.

→ Connect a repo (free)

Step 4 -- Local validation with stateanchor check

Validate your stateanchor.yaml before pushing. Run from your repo root:

node bin/stateanchor-check.js

Runs 17 structural rules, outputs ERR / WARN / INFO findings. No network call, no authentication. Exits 1 on ERR findings so you can wire it into a pre-commit hook.

See the CLI reference for all flags (--config, --fail-on, --json).

What to expect

• First sync: StateAnchor builds the initial IR baseline. No gate verdict on the first sync -- it establishes the reference point.
• Subsequent PRs: every push diffs your spec against the prior snapshot. ERR findings block the merge and post a PR annotation explaining exactly what changed; WARN findings are flagged; INFO findings pass silently.
• Gate blocked? See Handling a block -- you can fix the spec, file a scoped exception, or roll back to last known good.

Related

• Express.js integration guide
• stateanchor.yaml reference -- full spec for all fields
• Gate kinds reference -- all 33 ERR / WARN / INFO kinds
• GitHub Action reference -- inputs, outputs, OIDC, mode options
• CLI reference -- full stateanchor check documentation
• Handling a block -- what to do when the gate returns ERR