Skip to navigation

Use the CLI in CI/CD

Run ast push and ast deploy -f as an app, with no personal login

View as Markdown

When ASTRO_CLIENT_ID and ASTRO_CLIENT_SECRET are set, the CLI signs in as an app instead of a person. An app is an identity that belongs to one account, holds only the scopes granted to it, and keeps working when its creator leaves the account.

export ASTRO_CLIENT_ID=<client-id>
export ASTRO_CLIENT_SECRET=<client-secret>
ast push --yes
ast deploy -f astropods.deploy.yml

The CLI exchanges the client ID and secret for a short-lived token, renews it before it expires, and keeps it in memory only. No ast login or ast account switch is needed: the account comes from the app.

Environment variables

VariableRequiredValue
ASTRO_CLIENT_IDYesThe app’s client ID
ASTRO_CLIENT_SECRETYesOne of the app’s client secrets
ASTRO_ACCOUNTNoThe account to act on. The command fails if it names an account other than the app’s

Supported commands

CommandRequired scopes
ast pushblueprint:create, blueprint:edit, blueprint:read
ast deploy -fblueprint:read, blueprint:edit, deployment:create, deployment:edit, deployment:operate, deployment:read

A scope applies to every resource of that kind in the app’s account. An app acts only on its own account.

Other commands that call Astropods require a person, and fail when run as an app. ast login and ast account switch refuse to run while ASTRO_CLIENT_ID is set.

Create the credentials

Creating an app requires the app:manage permission, which account administrators hold.

1

Create the app

Go to Settings > OAuth apps. In an organization, open the organization’s settings first. Select New OAuth app and keep As itself selected.

2

Add scopes

Open the app, select Add scopes, and add the scopes for each command the job runs.

3

Add a client secret

Select Add a client secret and copy the client ID and secret. The secret is shown once. Store both in your CI system’s secret store as ASTRO_CLIENT_ID and ASTRO_CLIENT_SECRET.

Examples

ast push builds the image on the runner, so the runner requires Docker. The installer adds ~/.ast/bin to the shell profile, which CI steps don’t read, so each example adds it to PATH.

.github/workflows/astropods.yml
name: Deploy to Astropods
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install the Astropods CLI
run: |
curl -fsSL https://astropods.com/install | sh
echo "$HOME/.ast/bin" >> "$GITHUB_PATH"
- name: Push and deploy
run: |
ast push --yes
ast deploy -f astropods.deploy.yml
env:
ASTRO_CLIENT_ID: ${{ secrets.ASTRO_CLIENT_ID }}
ASTRO_CLIENT_SECRET: ${{ secrets.ASTRO_CLIENT_SECRET }}

Repository secrets are under Settings > Secrets and variables > Actions.

Behavior as an app

  • ast push requires --yes. Push stops on a blueprint that already exists unless the current checkout pushed it before. A CI checkout has no record of earlier pushes.
  • Deployments have no web access. A deployment an app creates has no one on its web interface. Grant access on the deployment’s page, or set public in astropods.deploy.yml.
  • The audit log names the app. Each push and deploy shows the app as the actor in Settings > Audit log.

Rotate and revoke

ActionEffect
Add a second client secret, switch the job to it, delete the firstRotates the secret with no downtime
Delete the appThe app’s next request fails
Remove the app’s scopesThe app still signs in, and every command is refused

Errors

Each error prints a headline, the error that caused it, and a fix.

✗ This app isn't allowed to do this
↳ This app does not hold the deployment:operate scope on this account.
→ Add the deployment:operate scope to the app in Settings > OAuth apps, then run the command again.
HeadlineCauseFix
Signing in as an app failedThe client ID or secret is wrong, or the secret was deletedAdd a new client secret and update the job’s secrets
This app isn't allowed to do thisThe app lacks the scope the reason namesAdd that scope on the app
This command can't run as an appThe command requires a personRun it on your own machine after ast login
'ast login' needs a personThe job runs ast login or ast account switchRemove the command
ASTRO_ACCOUNT names the wrong accountASTRO_ACCOUNT names an account other than the app’sSet it to the app’s account, or remove it
Can't reach AstropodsThe runner can’t connect to AstropodsCheck the runner’s network access
ast: command not found~/.ast/bin isn’t on the step’s PATHAdd it to PATH, as in the examples

Next steps