Skip to main content
Workload Identity lets CI/CD pipelines and other automation call the Bytebase API with a short-lived OpenID Connect (OIDC) token issued by their own platform, instead of a stored key. Unlike Service Accounts that require storing API keys as secrets, Workload Identity:
  • Uses short-lived tokens generated per job
  • Validates tokens against the platform’s own OIDC issuer, so no secret is shared with Bytebase
  • Restricts access to specific repositories, branches, and workflows

​
Workspace vs Project Level

Workload identities can be created at two levels:
  • Workspace level — Has access governed by workspace IAM policies. Suitable for cross-project CI/CD workflows. Managed under IAM & Admin > Workload Identities; the email is {id}@workload.bytebase.com. Self-hosted only.
  • Project level — Scoped to a single project, following the principle of least privilege. Suitable for project-specific pipelines. Managed under the project’s Manage > Workload Identities; the email is {id}@{project-id}.workload.bytebase.com.
Creating or editing a workload identity requires Workspace Admin at the workspace level, or Project Owner at the project level.
Bytebase Cloud supports project-level workload identities only.

​
Supported Platforms

GitHub Actions

Configure OIDC authentication for GitHub Actions workflows

GitLab CI/CD

Configure OIDC authentication for GitLab CI/CD pipelines

Generic OIDC

Any issuer that signs JWTs and publishes its keys
Choosing GitHub Actions or GitLab CI as the Platform fills in the issuer and builds the subject pattern from the organization, repository, and branch you enter. Generic OIDC exposes the settings directly.

​
Configuration

Every workload identity, whichever platform it uses, carries the same four settings. Bytebase checks an incoming token against them in this order: A token is also rejected once its exp claim has passed. Bytebase does not read provider-specific claims such as repository_owner or namespace_path; everything it enforces is in the iss, aud, and sub claims.
Which audience to list depends on how the pipeline requests its token. Workflows that Bytebase generates on the project GitOps page request bytebase. The GitHub Actions guide requests https://github.com/{owner}, and the GitLab CI/CD guide requests the GitLab instance URL. Add each audience your pipelines actually use.

​
Generic OIDC

Use this for an issuer that is not GitHub Actions or GitLab CI, such as Bitbucket Pipelines, CircleCI, Kubernetes service account tokens, or a cloud provider’s workload identity.
  1. Go to IAM & Admin > Workload Identities, or the project’s Manage > Workload Identities, and click Create.
  2. Enter a Name and Email prefix, and pick the Roles to grant.
  3. Set Platform to Generic OIDC.
  4. Fill in Issuer URL, Audience, and Subject Pattern with the values your issuer puts in its tokens. Set JWKS URL only if the issuer has no discovery document.
  5. Click Create.
Then, in the pipeline, request an ID token whose audience is on the list and exchange it:
The response carries an accessToken to send as Authorization: Bearer on API calls. It is valid for one hour, independent of the workspace’s access token duration setting.
Bytebase caches an issuer’s signing keys for 15 minutes. After the issuer rotates its keys, tokens signed with the new key may be rejected until the cache expires.
If Bytebase rejects a configuration, the error names the setting and the rule it broke; the same rules apply through the API and the Terraform provider.