- 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
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.
1. Create an API access token
Buildkite shows these steps in Managing API access tokens.- In Buildkite, open Personal Settings in the global navigation, then API Access Tokens.
- Select New API Access Token. Enter your password if Buildkite asks for it.
- Enter a description, for example
Opal. - Under Credential Type, keep Token. Do not choose Public Key. Opal needs the token value.
- Under Organization Access, select the organization you want Opal to manage.
- 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.
- 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.
- 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.- On the app’s Assets tab, select Import assets.
- Import Buildkite Organization, the teams, and the pipelines you want people to request.
- Turn on requests for those items.
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.
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