User and team permissions

Manage teams and permissions

Use teams to assign permissions to groups of users. Each team can have access to pipelines, test suites, registries, or a combination of these resources.

A Buildkite organization administrator must enable teams before you can manage team access. The following roles determine who can manage permissions:

To access or enable the teams feature for your organization, or both:

1. Select Settings in the global navigation to access the Organization Settings page.

2. Select Teams to access your organization's Teams page.

3. If the teams feature is not enabled, select Enable Teams to activate this feature.

When you first enable the teams feature, a team is automatically created for your organization called Everyone, which includes all users. This maintains existing access to pipelines for all the users in your Buildkite organization.

Without the Teams feature activated, all users are able to access all items within your Buildkite organization.

Organization-level permissions

A Buildkite organization administrator can manage all teams and their resource permissions. Select Settings in the global navigation to open the Organization Settings page.

From Settings > Teams, administrators can:

• Create a team using New Team.
• Manage team, pipeline, test suite, and registry settings across the organization.
• Delete a team by selecting the team > Settings > Delete Team.
• Enable or re-enable teams.
• Disable teams using Disable Teams, after deleting every team, including Everyone.

Administrators can also configure organization settings for Buildkite Pipelines and Buildkite Package Registries, manage integrations, and view usage reports and audit logs.

Team-level permissions

A team maintainer manages a team's members, resource access, and settings. A Team Member can use the team's resources but cannot manage the team.

To open a team, select Teams in the global navigation > Teams, then select the team. If you are also an organization administrator, use Settings > Teams instead, as described in Organization-level permissions.

Manage team members

Use the Members tab to:

• Add an existing organization user using Add Member.
• Filter by role using Everyone, Team Member, or Team Maintainer in the role dropdown.
• Remove a user using their Remove button.

Set resource permissions

Select the resource's tab, then its permission level. These permissions apply to all members of the team:

Registry permissions are available after Buildkite Package Registries has been enabled.

All team members receive the same access to each resource through that team. Create separate teams when groups need different access levels.

Check your own access before reducing a team's permissions:

Configure team settings

Use the team's Settings tab to configure:

• Visibility: Control the team's visibility.
• Automatically add new users to this team: Add new organization members to the team.
• Default Member Role: Choose Member or Maintainer for new team members.
• Team Member Permissions: Allow any combination of Create pipelines, Create test suites, Create registries, Delete registries, and Delete packages.

Team maintainers can still create and add pipelines, test suites, and registries when these team member permissions are removed.

The Create test suites permission appears only when your plan includes Test Engine. Otherwise, the setting is hidden. Any saved value is restored if Test Engine becomes available again.

To delete the team, use Delete on the Settings tab.

Programmatically managing teams

You can programmatically manage your teams using our GraphQL API. If you're creating pipelines programmatically using the REST API, you can add them directly to teams using the team's UUID. More information about creating pipelines can be found in our REST API documentation.

You can also restrict agents to specific teams with the BUILDKITE_BUILD_CREATOR_TEAMS environment variable. Using agent hooks, you can allow or disallow builds based on the creator's team memberships.

For example, the following environment hook prevents anyone from outside of the ops team from running a build on the agent:

set -euo pipefail

if [[ ":$BUILDKITE_BUILD_CREATOR_TEAMS:" != *":ops:"* ]]; then
  echo "You must be in the ops team to run a job on this agent"
  exit 1
fi

Frequently asked questions

Is there a limit to the number of teams an organization can have?

Yes, Buildkite has a limit of 250 teams per organization. If you are an Enterprise plan customer and require additional teams, please contact support@buildkite.com.

Will users (and API tokens) still have access to their pipelines?

When you enable the teams feature, a default team called "Everyone" is created, containing all your users and pipelines. This ensures that users, and their API tokens, will still have access to their pipelines.

How does Teams work with SSO?

When a user joins the organization using SSO, they'll be automatically added to any teams that have the "Automatically add new users to this team" setting enabled.

Can I delete the "Everyone" team?

Yes, you can delete or edit the "Everyone" team. To ensure uninterrupted access to pipelines we recommend creating new teams before deleting the "Everyone" team.

Can I set separate permissions specifically on rebuilds?

No, rebuilds are in the same category with builds. Therefore, all team members with permissions to run builds on a certain pipeline are also able to perform rebuilds.

Once enabled, can I disable teams?

Yes, you can disable teams by deleting all your teams, and then selecting "Disable Teams".

Can I automate the removal of users from Buildkite?

Yes. Use the GraphQL API with a GraphQL API token to remove organization members.

1. Find your organization's slug in Organization Settings.
2. Confirm the user's name or email in their team.
3. Run the query below. Replace your-organization-slug with your organization's slug and Jane Doe with the user's name or email. Verify the result before removing the user.

query FindOrganizationMember {
  organization(slug: "your-organization-slug") {
    members(first: 1, search: "Jane Doe") {
      edges {
        node {
          id # You will need to use this info on the next step as OrganizationMember.id
          user {
            # Double check that this is the right user you are about to remove
            name
            email
          }
        }
      }
    }
  }
}

Copy the user ID you've received into the following mutation and run it to remove the user from your Buildkite organization:

mutation RemoveOrganizationMember {
  organizationMemberDelete(input: { id: "user-ID-you-copied-goes-here" }) {
    deletedOrganizationMemberID
  }
}

Removing users during a security incident

Remove a suspected compromised user from your Buildkite organization immediately to revoke their access to organization data. If you use SSO, also disable their access at the identity provider to prevent them from rejoining.

For the wider response, including token revocation, secret rotation, investigation, and recovery, follow Incident response.

You can remove a user in your organization's Settings in the Buildkite interface.

A Buildkite organization administrator can also delete organization members using GraphQL. To do this:

1. Find the id for the user to be deleted (in this example Jane Doe):

   query {
     organization(slug: "your-organization-slug") {
       members(search: "Jane Doe", first: 10) {
         edges {
           node {
             role
             user {
               name
             }
             id
           }
         }
       }
     }
   }
   

2. Use the id from the previous query in a mutation:

   mutation deleteOrgMember {
     organizationMemberDelete(input: { id: "abc123" }) {
       organization {
         name
       }
       deletedOrganizationMemberID
       user {
         name
       }
     }
   }
   

Security guarantees of removing a user

Removing a user blocks their active sessions from reading or changing your organization's data through the web interface or APIs. The user can still access their personal settings and any other organizations they belong to.

If this is the user's final organization membership, removing them also revokes all their API access tokens and OAuth authorizations. If the user still belongs to another organization, credentials that retain access to that organization remain valid.

Organization administrators cannot end a user's account-wide sessions. Buildkite accounts belong to individuals and can span multiple organizations.

If you cannot work with the affected user, or several accounts are compromised, send the affected user IDs to support@buildkite.com. Ask Buildkite support to end all sessions for those users.

If the affected user can help, ask them to log out and reset their password to reset all active sessions. Verify that their account is secure before adding them back to your organization.

Password reset may not be available to SSO users who have no Buildkite password.

Removing users from an organization with enabled SSO

Disable or remove the compromised account at your SSO provider as well as in Buildkite. Otherwise, an attacker with SSO access can log in again and create a new organization membership.

Rejoining does not restore revoked authorizations or authorize other existing sessions. However, a new SSO login can grant access under your organization's default SSO permissions.

If the attacker controls your SSO provider, changes in Buildkite alone cannot resolve the incident.

Disabling and re-enabling SSO

To revoke all SSO sessions during an incident without disabling your providers, require SSO sign-in again. The following procedure is only needed if you also need to disable a provider.

The other control you have is the organization membership's SSO mode. If the membership requires SSO, the user will only have access to your organization in the particular sessions authenticated through your SSO provider.

Disabling an SSO provider revokes its active SSO authorizations, including the administrator's. The administrator must log back in using a non-SSO method. After the provider is re-enabled, members required to use it must re-authorize.

You can disable and re-enable the SSO using GraphQL or the Buildkite UI.

An attacker with an authenticated session may have created API tokens, which are not subject to SSO requirements. Resetting SSO authorizations is not a substitute for removing the compromised user from your Buildkite organization.