> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Use the CLI in CI/CD

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.

```bash
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

| Variable              | Required | Value                                                                                |
| --------------------- | -------- | ------------------------------------------------------------------------------------ |
| `ASTRO_CLIENT_ID`     | Yes      | The app's client ID                                                                  |
| `ASTRO_CLIENT_SECRET` | Yes      | One of the app's client secrets                                                      |
| `ASTRO_ACCOUNT`       | No       | The account to act on. The command fails if it names an account other than the app's |

## Supported commands

| Command         | Required scopes                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `ast push`      | `blueprint:create`, `blueprint:edit`, `blueprint:read`                                                              |
| `ast deploy -f` | `blueprint: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](/access-control) hold.

#### 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.

#### Add scopes

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

#### 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 Actions

**`.github/workflows/astropods.yml`**

```yaml title=".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**.

#### GitLab CI

**`.gitlab-ci.yml`**

```yaml title=".gitlab-ci.yml"
deploy:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - curl -fsSL https://astropods.com/install | sh
    - export PATH="$HOME/.ast/bin:$PATH"
    - ast push --yes
    - ast deploy -f astropods.deploy.yml
```

Project variables are under **Settings** > **CI/CD** > **Variables**. GitLab passes them to the job's environment. Mark `ASTRO_CLIENT_SECRET` as masked, and run the job on a runner with Docker.

## 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

| Action                                                             | Effect                                               |
| ------------------------------------------------------------------ | ---------------------------------------------------- |
| Add a second client secret, switch the job to it, delete the first | Rotates the secret with no downtime                  |
| Delete the app                                                     | The app's next request fails                         |
| Remove the app's scopes                                            | The app still signs in, and every command is refused |

## Errors

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

```text
✗ 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.
```

| Headline                                | Cause                                                       | Fix                                                  |
| --------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
| `Signing in as an app failed`           | The client ID or secret is wrong, or the secret was deleted | Add a new client secret and update the job's secrets |
| `This app isn't allowed to do this`     | The app lacks the scope the reason names                    | Add that scope on the app                            |
| `This command can't run as an app`      | The command requires a person                               | Run it on your own machine after `ast login`         |
| `'ast login' needs a person`            | The job runs `ast login` or `ast account switch`            | Remove the command                                   |
| `ASTRO_ACCOUNT names the wrong account` | `ASTRO_ACCOUNT` names an account other than the app's       | Set it to the app's account, or remove it            |
| `Can't reach Astropods`                 | The runner can't connect to Astropods                       | Check the runner's network access                    |
| `ast: command not found`                | `~/.ast/bin` isn't on the step's `PATH`                     | Add it to `PATH`, as in the examples                 |

## Next steps

* [Deploy Spec](/deploy-spec): the `astropods.deploy.yml` format
* [ast blueprint](/cli/blueprint): every push and deploy flag
* [Install the CLI](/install-cli): other ways to install `ast`