# CI/CD

Use a scoped API token and a non-interactive release command to publish from
continuous integration. The example below targets GitHub Actions, but the same
token and command work in other CI systems.

> **Availability:** `@rollbird/cli` and `@rollbird/react-native` are available
> from the public npm registry, so the workflow below installs the same
> packages developers use locally.

## Create a release token

Open **Dashboard → Settings → API tokens** and create a token with both scopes:

- `release:write` creates, uploads, publishes, changes rollout, and rolls back releases.
- `release:read` reads project status, release history, and release metrics.

Bind the token to the project that the workflow releases. A project-bound
token cannot access another project or organization-wide routes. The dashboard
shows the plaintext token once; Rollbird stores only its hash.

Copy the value immediately and save it as the repository secret
`ROLLBIRD_TOKEN`. Never put it in workflow YAML, source code, logs, or
`rollbird.json`.

## GitHub Actions workflow

This workflow installs a pnpm-based React Native project and publishes a
production release after the `Verify` job succeeds. Save it as
`.github/workflows/rollbird.yml` in the consumer app.

```yaml
name: Rollbird production release

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

  release:
    needs: verify
    runs-on: ubuntu-latest
    env:
      ROLLBIRD_TOKEN: ${{ secrets.ROLLBIRD_TOKEN }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec rollbird release --production --yes --message "${{ github.sha }}"
```

The example workflow itself was not executed while this guide was authored;
it requires a consumer repository, a real token, and the public packages. Its
Rollbird command and flags are covered by the CLI tests.

For npm, Yarn, or Bun projects, replace the setup and install steps with the
package manager the app already uses. Keep Node.js 20 or newer and invoke the
project-local `rollbird` executable.

## Non-interactive requirements

CI must provide `ROLLBIRD_TOKEN`. The CLI reads it before saved credentials, so
there is no reason to run `rollbird login` in a job.

Production releases require explicit confirmation. Add `--yes` in CI:

```bash
pnpm exec rollbird release --production --yes
```

Run the command from the directory containing `rollbird.json`. Use
`--platform ios` or `--platform android` when a job builds only one platform.
Use `--rollout` for a staged deployment:

```bash
pnpm exec rollbird release --production --rollout 10 --yes
```

Apps using the `appVersion` strategy must supply the target version:

```bash
pnpm exec rollbird release --production --target-app-version 2.4.0 --yes
```

## Preview environments

Publish pull-request builds to a non-production channel rather than a binary
configured for production. The channel still has to match the one embedded in
the test binary.

```bash
pnpm exec rollbird release --channel preview --yes --message "PR ${GITHUB_REF_NAME}"
```

`--yes` is harmless on preview and keeps the job non-interactive. Rollbird
records supported CI metadata such as the provider, commit, branch, and author
when the environment exposes it.

## Machine-readable output

Put `--json` before the command to emit one JSON result to stdout. Human
progress and errors go to stderr, which keeps stdout safe for downstream job
steps.

```bash
pnpm exec rollbird --json status
```

The CLI exit code is the stable automation contract:

| Exit | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Release build or local operation failed |
| `2` | Usage, configuration, validation, or ordinary API client error |
| `3` | Authentication failed or credentials are missing |
| `4` | The plan blocks the requested action |
| `5` | Network, storage, or server failure |

## Token rotation

Create a replacement token, update the CI secret, run the workflow once, then
revoke the old token in the dashboard. Do not widen a token to compensate for
a failing job: verify its project binding and required scope first.

Token management itself is session-only. API tokens cannot create, list, or
revoke other tokens, and a project-bound token cannot reach organization-wide
resources.