Workload Identity for GitHub Actions

This guide explains how to configure Workload Identity for GitHub Actions 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	`GitHub Actions Deploy`
Email	Unique email prefix. Bytebase appends `@workload.bytebase.com`, or `@{project-id}.workload.bytebase.com` for a project-level identity	`github-actions-deploy`
Roles	Roles granted to the identity	`GitOps Service Agent`
Platform	Select GitHub Actions	`GitHub Actions`
Organization / Username	GitHub organization or username	`my-org`
Repository	Repository name. Leave empty to allow every repository in the organization	`my-repo`
Branch	Branch name. Leave empty to allow every branch	`main`
Audience	The audiences your workflow requests. `bytebase` is filled in for you; the workflow in this guide requests `https://github.com/{owner}`, so add that line	`https://github.com/my-org`

Click Create.

Bytebase builds the Subject Pattern from the organization, repository, and branch: repo:my-org/my-repo:ref:refs/heads/main. Leaving the branch empty gives repo:my-org/my-repo:*, and leaving the repository empty gives repo:my-org/*. Advanced Settings shows the pattern and the Issuer URL (https://token.actions.githubusercontent.com); edit the pattern there to match other refs, such as a tag or an environment. See Configuration for the rules every setting must satisfy.

On GitHub Enterprise Server, the token issuer and the default audience differ from GitHub.com. Set Issuer URL under Advanced Settings to your server’s issuer, and list the audience your getIDToken() call requests.

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., github-actions-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 GitHub Actions Workflow

In your GitHub Actions workflow, add the following configuration:

Request OIDC Token

Add id-token: write permission and use the actions/github-script action to get the token:

name: Deploy Database Changes

on:
  push:
    branches: [main]

permissions:
  id-token: write  # Required for OIDC token
  contents: read

env:
  BYTEBASE_URL: https://bytebase.example.com
  WORKLOAD_IDENTITY_EMAIL: github-actions-deploy@workload.bytebase.com

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

      - name: Get Bytebase Token
        id: bytebase-token
        uses: actions/github-script@v7
        with:
          script: |
            const token = await core.getIDToken('https://github.com/${{ github.repository_owner }}');
            core.setSecret(token);
            core.setOutput('token', token);

      - name: Exchange for Bytebase API Token
        id: exchange
        run: |
          RESPONSE=$(curl -s -X POST "${BYTEBASE_URL}/v1/auth:exchangeToken" \
            -H "Content-Type: application/json" \
            -d "{\"token\": \"${{ steps.bytebase-token.outputs.token }}\", \"email\": \"${WORKLOAD_IDENTITY_EMAIL}\"}")

          ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
          echo "::add-mask::$ACCESS_TOKEN"
          echo "access_token=$ACCESS_TOKEN" >> $GITHUB_OUTPUT

      - name: Call Bytebase API
        run: |
          curl -s "${BYTEBASE_URL}/v1/projects" \
            -H "Authorization: Bearer ${{ steps.exchange.outputs.access_token }}"

Complete Example

Here’s a complete workflow that creates a database change using Workload Identity:

name: Database Schema Change

on:
  push:
    branches: [main]
    paths:
      - 'migrations/**'

permissions:
  id-token: write
  contents: read

env:
  BYTEBASE_URL: https://bytebase.example.com
  WORKLOAD_IDENTITY_EMAIL: github-actions-deploy@workload.bytebase.com
  PROJECT: projects/my-project

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

      - name: Get OIDC Token
        id: oidc
        uses: actions/github-script@v7
        with:
          script: |
            const token = await core.getIDToken('https://github.com/${{ github.repository_owner }}');
            core.setSecret(token);
            core.setOutput('token', token);

      - name: Exchange Token
        id: auth
        run: |
          RESPONSE=$(curl -s -X POST "${BYTEBASE_URL}/v1/auth:exchangeToken" \
            -H "Content-Type: application/json" \
            -d "{\"token\": \"${{ steps.oidc.outputs.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

          echo "::add-mask::$ACCESS_TOKEN"
          echo "access_token=$ACCESS_TOKEN" >> $GITHUB_OUTPUT

      - name: Create Plan
        id: plan
        run: |
          # Read migration SQL file
          SQL_CONTENT=$(cat migrations/latest.sql | jq -Rs .)

          RESPONSE=$(curl -s -X POST "${BYTEBASE_URL}/v1/${PROJECT}/plans" \
            -H "Authorization: Bearer ${{ steps.auth.outputs.access_token }}" \
            -H "Content-Type: application/json" \
            -d "{
              \"title\": \"Migration from GitHub Actions\",
              \"steps\": [{
                \"specs\": [{
                  \"changeDatabaseConfig\": {
                    \"target\": \"instances/prod/databases/mydb\",
                    \"type\": \"MIGRATE\",
                    \"sheet\": \"${SQL_CONTENT}\"
                  }
                }]
              }]
            }")

          PLAN_NAME=$(echo $RESPONSE | jq -r '.name')
          echo "plan_name=$PLAN_NAME" >> $GITHUB_OUTPUT

Troubleshooting

Token Exchange Fails

If the token exchange returns an error:

Verify the repository and branch: Check that the workflow’s repository and branch match the Subject Pattern shown under Advanced Settings.
Check the audience: The aud your getIDToken() call requests must be on the identity’s Audience list. This guide requests https://github.com/{owner}; workflows generated on the project GitOps page request bytebase.
Upgraded from 3.22 or earlier: An identity whose pipeline requests an audience that is not listed, or whose subject pattern matches every repository (repo:*), 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:

- name: Debug Token
  run: |
    echo "${{ steps.oidc.outputs.token }}" | cut -d. -f2 | base64 -d | jq .

This shows the token’s claims. Bytebase checks iss, aud, and sub against the identity’s settings; see Configuration.

AI

Security

General

Workload Identity for GitHub Actions

Step 1: Create a Workload Identity in Bytebase

Step 2: Assign Roles

Step 3: Configure GitHub Actions Workflow

Request OIDC Token

Complete Example

Troubleshooting

Token Exchange Fails

Permission Denied

Debug Token Claims

​Step 1: Create a Workload Identity in Bytebase

​Step 2: Assign Roles

​Step 3: Configure GitHub Actions Workflow

​Request OIDC Token

​Complete Example

​Troubleshooting

​Token Exchange Fails

​Permission Denied

​Debug Token Claims

Step 1: Create a Workload Identity in Bytebase

Step 2: Assign Roles

Step 3: Configure GitHub Actions Workflow

Request OIDC Token

Complete Example

Troubleshooting

Token Exchange Fails

Permission Denied

Debug Token Claims