Skip to content

Use Anchor in CI

CI jobs do not log in. They use a service token: a bearer token tied to one project, scoped to environments and folders, read-only or read-write, with an expiry of 1 to 365 days.

A project admin creates it in the dashboard (Settings → Service tokens) or with the CLI:

Terminal window
anchor tokens create --name github-deploy --scope prod --permission read --project my-app
  • --scope <env> or --scope <env>:<path> (repeatable, up to 20). A folder scope covers its subfolders: --scope prod:/api reads /api and /api/v2, not /.
  • --permission read (default) or read-write.
  • --expires-in <days>, 1–365, default 90, or never (see below).

The token is shown once. Store it as a CI secret named ANCHOR_TOKEN, then forget it.

jobs:
deploy:
runs-on: ubuntu-latest
env:
ANCHOR_API_URL: https://anchor.example.com
ANCHOR_TOKEN: ${{ secrets.ANCHOR_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: sotarak/anchor/setup-action@v0.5.3
with:
version: 0.5.3
- run: anchor run --project my-app --env prod -- npm run deploy

The action downloads the release binary for the runner (Linux, macOS or Windows), verifies it against the release’s SHA256SUMS, and puts anchor on PATH. version defaults to latest; pin it for reproducible builds. The installed version is available as the step output version.

A tag such as @vX.Y.Z can be moved by whoever controls the repository. For a job that holds production tokens, pin the action to the release’s full commit SHA instead (uses: sotarak/anchor/setup-action@<40-character sha> # vX.Y.Z), as Anchor’s own workflows do, and let Dependabot’s github-actions updates bump it.

On other CI systems, or when Node.js is already on the runner, either of these works too:

Terminal window
curl -fsSL https://sotarak.github.io/anchor/install.sh | ANCHOR_VERSION=0.5.3 sh # ~/.local/bin
npx -y @anchor-secrets/cli@0.5.3 run --project my-app --env prod -- npm run deploy
  • Set ANCHOR_API_URL next to ANCHOR_TOKEN. The CLI only sends ANCHOR_TOKEN to an API URL from --api-url, ANCHOR_API_URL or the user config, never to the URL in a committed .anchor.json: a pull request cannot redirect your token to another host. Without it the CLI exits 2.
  • anchor run removes ANCHOR_TOKEN from the command’s environment, so the build or deploy script never sees the CI token. Pass --pass-token when the command runs anchor or the SDK itself. Secrets with reserved names (PATH, NODE_OPTIONS, LD_PRELOAD, proxies, ANCHOR_*, …) are skipped with a warning; --allow-reserved injects them.
  • anchor run starts the command only after every secret was fetched. A failed fetch (expired or revoked token, missing scope) exits 3 or 4 and the command never runs with a partial environment.
  • anchor export --format dotenv --output .env writes a file with mode 0600 if a tool needs one; prefer anchor run, which writes nothing to disk.
  • Revoke a token in Settings → Service tokens or with anchor tokens revoke <id>. The next request with it fails: there is no cache.
  • The token list shows when each token was last used. Every value read and every write with a token is in the project’s audit log under that token; listing secret names is not audited.
  • To rotate, create the new token, update the CI secret, then revoke the old one.

A machine that runs for years (a home server, an internal deploy box) can use a token that stays valid until it is revoked:

Terminal window
anchor tokens create --name home-server --scope prod --expires-in never

The CLI warns This token stays valid until you revoke it, and the token list shows never in the EXPIRES column. Such a token is a standing credential: nothing retires it if it leaks. Scope it to the narrowest environment and folder, prefer read, and revoke it as soon as the machine no longer needs it. Choose a dated token whenever someone can rotate it.