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.
1. Create a token
Section titled “1. Create a token”A project admin creates it in the dashboard (Settings → Service tokens) or with the CLI:
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:/apireads/apiand/api/v2, not/.--permission read(default) orread-write.--expires-in <days>, 1–365, default 90, ornever(see below).
The token is shown once. Store it as a CI secret named ANCHOR_TOKEN, then forget it.
2. Use it in the job
Section titled “2. Use it in the job”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 deployThe 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:
curl -fsSL https://sotarak.github.io/anchor/install.sh | ANCHOR_VERSION=0.5.3 sh # ~/.local/binnpx -y @anchor-secrets/cli@0.5.3 run --project my-app --env prod -- npm run deploy- Set
ANCHOR_API_URLnext toANCHOR_TOKEN. The CLI only sendsANCHOR_TOKENto an API URL from--api-url,ANCHOR_API_URLor 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 runremovesANCHOR_TOKENfrom the command’s environment, so the build or deploy script never sees the CI token. Pass--pass-tokenwhen the command runsanchoror the SDK itself. Secrets with reserved names (PATH,NODE_OPTIONS,LD_PRELOAD, proxies,ANCHOR_*, …) are skipped with a warning;--allow-reservedinjects them.anchor runstarts 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 .envwrites a file with mode 0600 if a tool needs one; preferanchor run, which writes nothing to disk.
Rotate and revoke
Section titled “Rotate and revoke”- 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.
Tokens without an expiry
Section titled “Tokens without an expiry”A machine that runs for years (a home server, an internal deploy box) can use a token that stays valid until it is revoked:
anchor tokens create --name home-server --scope prod --expires-in neverThe 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.