> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Buildkite

> Learn how to connect Opal to Buildkite to manage the organization admin role, team membership, and team access to pipelines.

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

| Resource | Read | Grant and revoke access | Notes |
| - | - | - | - |
| Organization members | Yes | Role only | Matched by email. Opal does not invite or remove members. |
| Buildkite Organization | Yes | Yes | **Member** and **Admin**. One role per person. Revoking **Admin** returns the person to **Member**. Opal does not revoke **Member**. |
| Buildkite Team | Yes | Yes | **Member** and **Maintainer**. One role per person. |
| Buildkite Pipeline | Yes | Yes, through a team | **Read Only**, **Build & Read**, and **Full Access**. Buildkite grants pipeline access to a team, not to a person. |

## 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](https://buildkite.com/docs/platform/team-management/permissions) 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](https://buildkite.com/docs/apis/managing-api-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:

| Scope | What Opal uses it for |
| - | - |
| `read_organizations` | Sync people and organization roles |
| `write_organizations` | Change the organization **Admin** role |
| `read_teams` | Sync teams and who is on them |
| `write_teams` | Change team membership, and a team's access to a pipeline |
| `read_pipelines` | Sync pipelines |

You do not need `write_pipelines`. Pipeline access is changed through the team API, which `write_teams` covers. Leave GraphQL access off.

8. 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.

> [!NOTE]
>
> 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**.

| Field | Value |
| - | - |
| App name | A name for this Buildkite organization in Opal, for example `Buildkite`. |
| App admin | The owner who administers the app in Opal. |
| Description | A short description that helps requesters understand what this app is. |
| Visibility | Who in your organization can see the app. |
| Organization slug | The slug in your Buildkite URL. For `https://buildkite.com/acme`, the slug is `acme`. |
| API access token | The token from [step 1](#1-create-an-api-access-token). |

Opal checks the token when you save the app.

## 3. Check the app setup

Open the app's **Setup** tab. Opal runs three reads:

| Check | If it fails |
| - | - |
| Read members | The app is not healthy and sync does not run. The token needs `read_organizations`, and **Organization slug** must match the organization on the token. |
| Read teams | Opal warns you. The token needs `read_teams`, and Teams must be turned on. |
| Read pipelines | Opal warns you. The token needs `read_pipelines`. |

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.

> [!NOTE]
>
> 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:

| In Opal | In Buildkite | What it allows |
| - | - | - |
| Read Only | Read Only | View builds. |
| Build & Read | Build & Read | View, create, and manage builds. Cannot edit pipeline settings or grant access. |
| Full Access | Full Access | Build & Read, plus edit pipeline settings, archive or delete the pipeline, and grant other teams access. |

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.

> [!WARNING]
>
> 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

| What you see | What to do |
| - | - |
| An authentication error when you save the app | Copy the token again. Check that **Organization slug** is the organization selected under **Organization Access**, and that the token has not expired. |
| **Read members** fails on Setup | The token needs `read_organizations`, and the person who created it must still belong to that organization. |
| **Read teams** fails on Setup | Turn Teams on, and add `read_teams` to the token. If Buildkite says the plan does not include team permissions, team access is unavailable on this plan. |
| A grant fails with a permissions error | Add the missing write scope from step 1. `write_organizations` changes the organization role. `write_teams` changes team membership and pipeline access. The token's creator must still be an organization administrator. |
| A change for one person fails, and that person created the token | Buildkite will not let a token change its owner. Grant and revoke that person with a token from a different administrator, or move the Opal token to a dedicated administrator account. |
| A sync fails because Buildkite received too many requests | Buildkite allows about 100 API requests a minute for a token. Wait for the limit to reset, then sync again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.