Service Accounts

Service accounts provide machine identity for CI/CD pipelines. Unlike API keys, service accounts don’t require your master password — a single RELIC_SERVICE_TOKEN environment variable is all you need.

How It Works

Each service account has its own RSA key pair. The project key is wrapped with the service account’s public key, and the private key is encrypted with a token-derived key using HKDF-SHA256. At runtime, the CLI derives the decryption key from the service token, decrypts the private key, unwraps the project key, and decrypts your secrets — all in a single HTTP call. The server never sees the raw token or any plaintext keys.

Creating a Service Account

Service accounts are created through the CLI. You need to be the project owner and have a Pro plan.

relic service-account create --name "github-deploy"

With OIDC trust policy for GitHub Actions:

relic service-account create --name "github-deploy" --github myorg/myrepo --branch main

Options:

Flag	Required	Description
`-n, --name`	Yes	A descriptive name for the service account
`-p, --project`	No	Project ID (defaults to `relic.toml` or `RELIC_PROJECT_ID`)
`--expires-in`	No	Expiration in days (max 365)
`--github`	No	Enable OIDC for GitHub Actions (format: `org/repo`)
`--gitlab`	No	Enable OIDC for GitLab CI (format: `group/project`)
`--branch`	No	Branch restriction for OIDC (default: `*` for all branches)

The CLI will output a service token that is shown once. Store it immediately in your CI provider’s secret storage.

  Service Token (shown once):

  rsk_a1b2c3d4e5f6...

  Store this token in your CI provider's secret storage.
  Set it as RELIC_SERVICE_TOKEN in your pipeline environment.

Using in CI/CD

Set RELIC_SERVICE_TOKEN in your pipeline environment, then run as usual:

relic run -e production -- npm run deploy

No RELIC_PASSWORD or RELIC_API_KEY needed. The service token handles both authentication and decryption.

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

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

GitLab CI

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

Managing Service Accounts

List

relic service-account list --project <project-id>

Shows all service accounts for a project with their status, expiry, and last usage time. Collaborators can also list service accounts.

Revoke

relic service-account revoke --name "github-deploy" --project <project-id>

Revocation is immediate. Any pipeline using the revoked token will fail on the next run. Only the project owner can revoke service accounts.

Limits

Maximum 5 active service accounts per project
Maximum expiration of 365 days
Expired and revoked accounts don’t count toward the limit
Requires a Pro plan

Service Accounts vs API Keys

	Service Account	API Key
Env vars needed	`RELIC_SERVICE_TOKEN`	`RELIC_API_KEY` + `RELIC_PASSWORD`
HTTP calls	1	2
Master password in CI	No	Yes
Scoped to	One project	Any project (or one)
Key management	Own RSA key pair	Uses owner’s keys

Using RELIC_API_KEY with RELIC_PASSWORD in CI is deprecated. Migrate to service accounts for better security and simpler configuration.

OIDC Trust Policies

Service accounts can be hardened with OIDC trust policies, which verify the CI platform’s identity before allowing access. When configured, the service token only works when paired with a valid OIDC token from the trusted provider. See the OIDC Trust Policies guide for setup instructions.

Key Rotation

When a project key is rotated (e.g. after revoking a collaborator’s share with rotation), active service accounts are automatically re-wrapped with the new key. No action is needed on your part — existing service tokens continue to work.

Security Considerations

Store RELIC_SERVICE_TOKEN in your CI provider’s secret storage. Never hardcode it in pipeline files or commit it to your repository.

Each service account is scoped to exactly one project
The service token is shown once at creation time and cannot be retrieved later
Service accounts can be revoked instantly from the CLI
All service account usage is logged in the audit trail
Projects with active service accounts cannot be archived — revoke them first
The raw token never reaches the Relic server; only a SHA-256 hash is stored

Getting Started

Guides

Configuration

Development

Reference

Service Accounts

How It Works

Creating a Service Account

Using in CI/CD

GitHub Actions

GitLab CI

Managing Service Accounts

List

Revoke

Limits

Service Accounts vs API Keys

OIDC Trust Policies

Key Rotation

Security Considerations

​How It Works

​Creating a Service Account

​Using in CI/CD

​GitHub Actions

​GitLab CI

​Managing Service Accounts

​List

​Revoke

​Limits

​Service Accounts vs API Keys

​OIDC Trust Policies

​Key Rotation

​Security Considerations

How It Works

Creating a Service Account

Using in CI/CD

GitHub Actions

GitLab CI

Managing Service Accounts

List

Revoke

Limits

Service Accounts vs API Keys

OIDC Trust Policies

Key Rotation

Security Considerations