Workload Identity for GitLab CI/CD

This guide explains how to configure Workload Identity for GitLab CI/CD to authenticate with Bytebase without storing long-lived credentials.

Step 1: Create a Workload Identity in Bytebase

Go to IAM & Admin > Workload Identities and click Create. For an identity scoped to one project, go to the project’s Manage > Workload Identities instead.
Fill in the configuration:

Field	Description	Example
Name	Display name for this identity	`GitLab CI Deploy`
Email	Unique email prefix. Bytebase appends `@workload.bytebase.com`, or `@{project-id}.workload.bytebase.com` for a project-level identity	`gitlab-ci-deploy`
Roles	Roles granted to the identity	`GitOps Service Agent`
Platform	Select GitLab CI	`GitLab CI`
Group / Username	GitLab group or username	`my-group`
Project	Project name. Leave empty to allow every project in the group	`my-project`
Allowed Branches/Tags	`All branches and tags`, `Specific branch`, or `Specific tag`, then the branch or tag name	`Specific branch`, `main`
Audience	The audiences your pipeline requests. `bytebase` is filled in for you; the pipelines in this guide request the GitLab instance URL, so add that line	`https://gitlab.com`

Click Create.

Bytebase builds the Subject Pattern from the group, project, and ref: project_path:my-group/my-project:ref_type:branch:ref:main. Allowing all branches and tags gives project_path:my-group/my-project:*, and leaving the project empty gives project_path:my-group/*. Advanced Settings shows the pattern and the GitLab URL (the token issuer, https://gitlab.com by default). See Configuration for the rules every setting must satisfy.

Step 2: Assign Roles

The Roles you picked in Step 1 are granted when the identity is created, so nothing more is needed for a new identity. To change its roles later, or if the Roles field was not shown because your account cannot set the IAM policy, grant them from the project:

Go to your project’s Settings > Members.
Click Grant Access.
Enter the Workload Identity email (e.g., gitlab-ci-deploy@workload.bytebase.com).
Select the GitOps Service Agent role.
Click Confirm.

The GitOps Service Agent role is designed for automated CI/CD workflows, allowing the identity to create and execute database changes. See Roles and Permissions for details.

Step 3: Configure GitLab CI/CD Pipeline

In your GitLab CI/CD pipeline, add the following configuration:

Request OIDC Token

Add id_tokens configuration to get the JWT token from GitLab:

stages:
  - deploy

deploy-database:
  stage: deploy
  image: alpine:latest
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com
  variables:
    BYTEBASE_URL: https://bytebase.example.com
    WORKLOAD_IDENTITY_EMAIL: gitlab-ci-deploy@workload.bytebase.com
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      # Exchange GitLab OIDC token for Bytebase API token
      RESPONSE=$(curl -s -X POST "${BYTEBASE_URL}/v1/auth:exchangeToken" \
        -H "Content-Type: application/json" \
        -d "{\"token\": \"${GITLAB_OIDC_TOKEN}\", \"email\": \"${WORKLOAD_IDENTITY_EMAIL}\"}")

      ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
      if [ "$ACCESS_TOKEN" = "null" ] || [ -z "$ACCESS_TOKEN" ]; then
        echo "Failed to get access token"
        echo "$RESPONSE"
        exit 1
      fi

      # Verify the token by calling the user info API
      USER_INFO=$(curl -s "${BYTEBASE_URL}/v1/users/me" \
        -H "Authorization: Bearer $ACCESS_TOKEN")
      echo "Authenticated as: $USER_INFO"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Complete Example

Here’s a complete GitOps workflow that uses Workload Identity to deploy database migrations:

# .gitlab-ci.yml
stages:
  - review
  - deploy

variables:
  BYTEBASE_URL: https://bytebase.example.com
  WORKLOAD_IDENTITY_EMAIL: gitlab-deploy@workload.bytebase.com

# SQL Review on merge requests
sql-review:
  stage: review
  image: bytebase/sql-review-action:latest
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com
  script:
    - |
      # Exchange OIDC token for Bytebase token
      export BYTEBASE_TOKEN=$(curl -s -X POST "${BYTEBASE_URL}/v1/auth:exchangeToken" \
        -H "Content-Type: application/json" \
        -d "{\"token\": \"${GITLAB_OIDC_TOKEN}\", \"email\": \"${WORKLOAD_IDENTITY_EMAIL}\"}" \
        | jq -r '.accessToken')

      # Run SQL review
      sql-review --url ${BYTEBASE_URL} --token ${BYTEBASE_TOKEN} \
        --file-pattern "migrations/**/*.sql"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - migrations/**

# Deploy on merge to main
rollout:
  stage: deploy
  image: bytebase/bytebase-action:latest
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com
  script:
    - |
      # Exchange OIDC token for Bytebase token
      export BYTEBASE_TOKEN=$(curl -s -X POST "${BYTEBASE_URL}/v1/auth:exchangeToken" \
        -H "Content-Type: application/json" \
        -d "{\"token\": \"${GITLAB_OIDC_TOKEN}\", \"email\": \"${WORKLOAD_IDENTITY_EMAIL}\"}" \
        | jq -r '.accessToken')

      # Create release and rollout
      bytebase-action rollout \
        --url ${BYTEBASE_URL} \
        --token ${BYTEBASE_TOKEN} \
        --file-pattern "migrations/**/*.sql" \
        --project projects/my-project \
        --targets instances/prod/databases/mydb
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - migrations/**

For more details on GitOps workflows, see GitOps Overview and Migration-Based Workflow.

Self-Hosted GitLab

For a self-hosted GitLab instance, request the token with your instance URL as the audience:

id_tokens:
  GITLAB_OIDC_TOKEN:
    aud: https://gitlab.your-company.com

In the workload identity, set GitLab URL under Advanced Settings to the same instance URL, since GitLab signs tokens with the instance as the issuer, and add the URL to the Audience list.

Troubleshooting

Token Exchange Fails

If the token exchange returns an error:

Verify the project path and branch: Check that the pipeline’s project path and ref match the Subject Pattern shown under Advanced Settings.
Check the audience: The aud in your id_tokens configuration must be on the identity’s Audience list. This guide requests the GitLab instance URL; pipelines generated on the project GitOps page request bytebase.
Check the issuer: GitLab URL must equal the token’s iss claim exactly, which is your instance URL for self-hosted GitLab.
Verify OIDC is enabled: GitLab CI/CD OIDC tokens require GitLab 15.7 or later.
Upgraded from 3.22 or earlier: An identity whose pipeline requests an audience that is not listed, or whose subject pattern matches every project (project_path:*), stops authenticating after the upgrade. See the 3.23.0 changelog.

Permission Denied

If API calls return permission errors:

Verify the Workload Identity has the GitOps Service Agent role assigned.
Check that the Workload Identity is a member of the target project.

Debug Token Claims

To inspect the OIDC token claims, decode the JWT:

script:
  - |
    echo "$GITLAB_OIDC_TOKEN" | cut -d. -f2 | base64 -d | jq .

This shows the token’s claims. Bytebase checks iss, aud, and sub against the identity’s settings; the project path and ref are matched through sub, and the namespace_path, project_path, and ref claims are not read. See Configuration.

AI

Security

General

Workload Identity for GitLab CI/CD

Step 1: Create a Workload Identity in Bytebase

Step 2: Assign Roles

Step 3: Configure GitLab CI/CD Pipeline

Request OIDC Token

Complete Example

Self-Hosted GitLab

Troubleshooting

Token Exchange Fails

Permission Denied

Debug Token Claims

​Step 1: Create a Workload Identity in Bytebase

​Step 2: Assign Roles

​Step 3: Configure GitLab CI/CD Pipeline

​Request OIDC Token

​Complete Example

​Self-Hosted GitLab

​Troubleshooting

​Token Exchange Fails

​Permission Denied

​Debug Token Claims

Step 1: Create a Workload Identity in Bytebase

Step 2: Assign Roles

Step 3: Configure GitLab CI/CD Pipeline

Request OIDC Token

Complete Example

Self-Hosted GitLab

Troubleshooting

Token Exchange Fails

Permission Denied

Debug Token Claims