Skip to main content
With the Buildkite integration, you can manage access to your Buildkite organization from Opal:
  • Let people request just-in-time access to the organization Admin role, and to a team as Member or Maintainer, from the web and Slack
  • Give a team Read Only, Build & Read, or Full Access on a pipeline
  • Delegate approvals to the right owners
  • Revoke access automatically when a time-bound grant expires
Opal connects to one Buildkite organization through an API access token. To manage several organizations, add a Buildkite app in Opal for each one.

Supported resources

Requirements

Before you begin, you must:
  • Be an Opal Admin.
  • Be a Buildkite organization administrator. The token acts as the person who creates it, and only an administrator can change organization roles and team access.
  • Turn on Teams for the organization. An organization administrator does this in Buildkite. If Buildkite says the plan does not include team permissions, team and pipeline access cannot be managed until the plan includes them.
  • Ask the Opal team to enable the Buildkite integration for your organization. If you do not see Buildkite under + App, contact your Opal admin or Opal support.
Use a dedicated administrator account for the token, and do not grant or revoke that account through Opal. Buildkite rejects changes to the token owner’s own role and team membership.

1. Create an API access token

Buildkite shows these steps in Managing API access tokens.
  1. In Buildkite, open Personal Settings in the global navigation, then API Access Tokens.
  2. Select New API Access Token. Enter your password if Buildkite asks for it.
  3. Enter a description, for example Opal.
  4. Under Credential Type, keep Token. Do not choose Public Key. Opal needs the token value.
  5. Under Organization Access, select the organization you want Opal to manage.
  6. Choose a Token Expiry. If you leave it unset, Buildkite expires the token after seven days. When it expires, Opal can no longer sync or change access, so set a reminder to replace it in Opal before that date.
  7. Under REST API Scopes, select only these scopes:
You do not need write_pipelines. Pipeline access is changed through the team API, which write_teams covers. Leave GraphQL access off.
  1. Select Create New API Access Token, enter your password if asked, and copy the token. Buildkite shows it only once. You enter it in Opal in the next step.
If the organization restricts API access by IP address, requests from Opal have to be allowed. That restriction is an Enterprise setting in Buildkite. Leaving Allowed IP Addresses empty on the token does not bypass an organization allowlist.

2. Create the Buildkite app in Opal

In Opal, go to Inventory > + App and select Buildkite. Opal checks the token when you save the app.

3. Check the app setup

Open the app’s Setup tab. Opal runs three reads: Opal cannot test the write scopes from Setup. A token missing write_organizations or write_teams still looks healthy until a grant fails.

4. Import the organization, teams, and pipelines

Opal pulls access only for items you import.
  1. On the app’s Assets tab, select Import assets.
  2. Import Buildkite Organization, the teams, and the pipelines you want people to request.
  3. Turn on requests for those items.
Organization members appear on the app’s Accounts tab after the next sync. Pending invitations are not synced. Create the person in Buildkite, or through your identity provider, before you grant them access in Opal.

How access maps to Opal

Organization role

The organization appears in Opal as Buildkite Organization, with Member and Admin. Each person holds one role, so requesting Admin replaces Member. Revoking Admin returns the person to Member. Opal does not revoke Member, so to remove people you should do so through your identity provider.
Do not make Member time-bound. Opal cannot take that role away when the grant expires.

Teams

Each team appears in Opal as a Buildkite Team, with Member and Maintainer. Each person holds one role on a team, so requesting the other role changes the existing one. Revoking that role removes the person from the team. Turning Teams on in an organization that has no teams creates Buildkite’s Everyone team and puts every current member on it. That team syncs into Opal like any other team.

Pipelines

Each pipeline appears in Opal as a Buildkite Pipeline. Buildkite does not assign a pipeline to a person. You grant a team one of these levels, and every member of that team receives it: A team holds one level on a pipeline. Requesting a different level replaces the current one. Revoking that level removes the team’s access to the pipeline. A person on two teams receives the higher level. For example, Read Only through one team and Full Access through another is Full Access in Buildkite.
Taking Full Access away from a team can leave nobody who can manage that pipeline, if it was their last team with Full Access. A Buildkite organization administrator can restore it.

What Opal does not manage

  • Inviting people to Buildkite, or removing them from the organization
  • The token owner’s own organization role or team membership
  • Creating, renaming, or deleting teams and pipelines
  • Test Engine suites and package registries
  • Clusters, agents, secrets, and organization security settings

Troubleshooting

Last modified on November 18, 2026