> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withrelic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Integration

> Use Relic in GitHub Actions, GitLab CI, and other CI/CD pipelines.

Relic works in CI/CD environments using **service accounts** (recommended) or API keys. Service accounts require only a single environment variable and don't need your master password.

## Service Accounts (Recommended)

Service accounts provide passwordless CI/CD integration. See the [Service Accounts guide](/guides/service-accounts) for full details.

<Steps>
  <Step title="Create a service account">
    ```bash theme={null}
    relic service-account create --name "ci-deploy"
    ```

    For GitHub Actions with OIDC (recommended):

    ```bash theme={null}
    relic service-account create --name "ci-deploy" --github myorg/myrepo --branch main
    ```

    The CLI outputs a service token. Store it in your CI provider's secret storage.
  </Step>

  <Step title="Set the environment variable">
    | Variable | Required | Description |
    | - | - | - |
    | `RELIC_SERVICE_TOKEN` | Yes | The service token from the previous step |
  </Step>

  <Step title="Run with secrets">
    ```bash theme={null}
    relic run -e production -- npm run deploy
    ```
  </Step>
</Steps>

## GitHub Actions

```yaml theme={null}
name: Deploy

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install Relic
        run: bun add -g relic

      - name: Deploy with secrets
        env:
          RELIC_SERVICE_TOKEN: ${{ secrets.RELIC_SERVICE_TOKEN }}
        run: relic run -e production -- npm run deploy
```

<Note>
  The `id-token: write` permission is required if you configured OIDC on your service account.
  Without OIDC, it can be omitted.
</Note>

## GitLab CI

```yaml theme={null}
deploy:
  stage: deploy
  image: oven/bun:latest
  script:
    - bun add -g relic
    - relic run -e production -- npm run deploy
  variables:
    RELIC_SERVICE_TOKEN: $RELIC_SERVICE_TOKEN
```

## Other Providers

Relic works with any CI/CD provider that supports environment variables. The pattern is always the same:

1. Install Relic (`bun add -g relic` or `npm install -g relic`)
2. Set `RELIC_SERVICE_TOKEN` in your pipeline environment
3. Run `relic run -e <environment> -- <your command>`

## OIDC Trust Policies

For additional security, add OIDC trust policies to your service accounts. This verifies the CI platform's identity so the service token only works from trusted environments. See the [OIDC Trust Policies](/guides/oidc) guide for details.

## API Keys (Legacy)

<Warning>
  Using `RELIC_API_KEY` with `RELIC_PASSWORD` in CI is deprecated. Migrate to [service
  accounts](/guides/service-accounts) for better security and simpler setup.
</Warning>

API keys still work but require two environment variables (`RELIC_API_KEY` + `RELIC_PASSWORD`) and expose your master password to the CI environment. To use API keys:

| Variable | Required | Description |
| - | - | - |
| `RELIC_API_KEY` | Yes | API key from the web dashboard |
| `RELIC_PASSWORD` | Yes | Your master password |
| `RELIC_PROJECT_ID` | No | Project ID (not needed if `relic.toml` is committed) |

## Scope Filtering

Use `--scope` to inject only a subset of secrets:

```bash theme={null}
relic run -e production -s client -- npm run build    # Client + shared secrets
relic run -e production -s server -- npm start         # Server + shared secrets
```

This is useful when your build step only needs client-side variables and shouldn't have access to server secrets.

## Folder Filtering

Use `--folder` to inject secrets from a specific folder:

```bash theme={null}
relic run -e production -f api -- npm start
relic run -e production -f web -- npm run build
```

Useful in monorepos where different services need different secrets from the same environment.

## Security Considerations

<Warning>
  Store `RELIC_API_KEY` and `RELIC_PASSWORD` in your CI provider's secret storage. Never hardcode
  them in pipeline files or commit them to your repository.
</Warning>

* API keys can be revoked from the web dashboard at any time
* Each API key has scoped permissions (`secrets.read`, `user.keys.read`)
* API keys can be scoped to a specific project, restricting access to only that project's secrets
* All API keys require an expiration date (maximum 365 days)
* API key usage is logged in the [audit trail](/configuration/audit-logs)
* The master password is used only for decryption and is never sent to the Relic server


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.