Skip to main content

Need the shared deploy token model?

Read the Fundamentals page for the shared deploy token model, then use this guide for CLI steps.

​
Why Deploy Tokens?

Deployment tokens let CI/CD runners fetch and decrypt Ghostable secrets without relying on a human-linked device. Each token targets a single environment and carries:
  • GHOSTABLE_CI_TOKEN — authenticates API calls (list, pull, deploy, etc.).
  • GHOSTABLE_DEPLOY_SEED — the private key used to derive environment keys.
Tokens are ideal for GitHub Actions, GitLab, Forge, Vapor, or any automation that should not hold a full CLI session.
Treat both secrets like production credentials. Store them in your CI secret manager and rotate regularly.

​
Creating a Token

Run the CLI wizard from a trusted workstation:
What happens next:
  1. You confirm (or override) the environment and name.
  2. The CLI mints a fresh keypair, registers the token, and re-shares the environment key with it.
  3. You receive the API token (GHOSTABLE_CI_TOKEN) plus the private key (GHOSTABLE_DEPLOY_SEED). If you enter a file path when prompted (or pass --out), the seed is written there with mode 600.
Example output:
If you misplace either secret, revoke the token and create a new one. Ghostable never stores the private key in plaintext.

​
Listing Tokens

See which tokens exist for a given environment:
The table shows the token name, status (active/revoked), last usage, and creation time. Use this to spot stale runners or confirm rotation.

​
Rotating a Token

Refresh the keypair (for example, before the API token expires) without changing the token ID:
Rotation steps:
  1. The CLI mints a new encryption keypair.
  2. Ghostable replaces the token’s public key.
  3. The environment key is re-shared with the rotated token and your current device.
  4. You receive a new private key; update GHOSTABLE_DEPLOY_SEED in your CI.
If you omit --token, the CLI prompts you to select from active tokens.

​
Revoking a Token

Remove access immediately when a runner is retired or compromised:
Revoking deletes the token server-side and re-shares the environment key with the remaining trusted identities. Once revoked, the token cannot be restored—create a new one if needed.

​
Tips

  • One token per environment: keep scopes tight so you can revoke/rotate without affecting other deployments.
  • Short expirations: the CLI supports limited lifetimes; shorter windows reduce blast radius.
  • Version control: never commit the .txt files produced by --out. Upload them to your secret manager and delete the local copy afterward.
  • If a token can’t decrypt: re-run ghostable deploy token rotate (or create) from a trusted device to re-share the environment key with that token.

​
Command Options Reference

​
string
Skip the prompt and target a specific environment by slug or ID.
​
string
Provide a display name ahead of time (defaults to <env>-ci).
​
string
Write the private key to a file instead of stdout. File is created with 0600 permissions.
​
string
List tokens for the given environment without prompting.
​
string
Specify the environment that owns the token you’re rotating.
​
string
Rotate a particular token ID without going through the picker.
​
string
Save the replacement private key to disk (same behavior as create).
​
string
Select the owning environment non-interactively.
​
string
Revoke a specific token ID without the interactive selection step.