5 min read

Local development

You do not need to push to GitHub to test a spec change. This page covers how to validate, preview gate decisions, and generate artifacts locally before committing.

Validate your spec locally

The fastest way to check if your stateanchor.yaml is valid is to parse it before pushing. StateAnchor's validation rules are deterministic -- the same spec that passes locally will pass in CI.

Using the API

If you have an API key, you can call the validation endpoint directly:

curl -X POST https://stateanchor.dev/api/action/validate \
  -H "Authorization: Bearer <your-action-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "config_content": "'"$(cat stateanchor.yaml)"'",
    "repo": "your-org/your-repo",
    "ref": "refs/heads/main",
    "commit_sha": "local-dev"
  }'

A 200 response with "valid": true means the spec is structurally correct. A 422 with errors array tells you exactly what to fix.

Manual validation checklist

If you prefer to validate without an API call, check these rules. They are the same rules Stage A enforces:

• service is a non-empty string, max 100 chars
• version is a quoted string, max 20 chars
• server.base_url starts with https://
• At least one endpoint exists
• Every endpoint has name, method, and path
• method is one of: GET, POST, PUT, PATCH, DELETE
• path starts with /
• Endpoint names are unique
• At least one output is configured under outputs
• File size is under 128 KB
• No YAML anchors or aliases

Preview what the gate would do

The gate decision depends on the diff between your current spec and the previously synced IR. To preview without triggering a real sync:

1. Make your spec change in stateanchor.yaml.
2. Think about what changed: did you remove an endpoint? That is an ERR lane item -- the gate will block. Did you add an optional field? That is INFO -- the gate will pass. Did you add a required parameter? That is WARN -- the gate will block if your warn_count_threshold is 1 (the default).
3. Refer to the gate engine reference for the full lane classification table.

The gate is deterministic. If you know the previous IR and the current spec, you can predict the gate decision without calling the API.

Generate SDKs locally

SDK generation currently runs server-side as part of the sync pipeline. There is no local generation CLI yet. To generate locally:

1. Push your spec change to a branch (not main).
2. Trigger a manual sync from the dashboard -- the gate evaluates and artifacts generate without affecting your main branch's state.
3. Download the generated artifacts from the project detail page.

A local generation CLI (stateanchor generate --local) is on the roadmap. Until then, branch-based syncs are the recommended workflow for previewing generated output.

Test the GitHub Action locally with act

act lets you run GitHub Actions workflows on your local machine. To test the StateAnchor action:

# Install act
brew install act    # macOS
# or: curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | bash

# Create a .env file with your action token
echo "STATEANCHOR_TOKEN=sa_live_..." > .secrets

# Run the action
act push --secret-file .secrets

Note: The OIDC token exchange (/api/action/oidc/exchange) requires a real GitHub OIDC JWT that act cannot generate. For local testing, use a pre-created API key instead of the OIDC flow.

Environment variables for local testing

Common local setup issues