Controlling user permissions

Pipeline permissions can be centrally managed by enabling Teams. Enterprise customers have the additional option to set fine-grained user permissions for their organization with the member Permissions page.

Permissions with teams

Enabling Teams for your organizations gives you control over each pipeline's permissions in one place. Teams can be enabled from your Organisation Settings in the Teams section.

When you first enable Teams, a team is automatically created for your organization called “Everyone” that contains all users. This maintains existing access to pipelines for all the users in your organization.

You can see the teams that you're a member of on the Teams page in your Buildkite settings. From this page, you can add new teams or edit existing ones. By clicking on a team, you can view the members, pipelines, and team specific settings.

Organization level permissions

Users who are organization admins can:

  • Enable and disable teams for their organization
  • Create new teams

Team level permissions

Users who are team maintainers can:

  • Add users to existing teams, of which they are the maintainer
  • Remove users from their teams
  • Set read, write, and edit permissions for users on pipelines in their team

All users in a team have the same level of access to the pipelines in their team. If you need to have more fine grained control over the pipelines in a team, you can create more teams with different permissions.

User level permissions

Any user can create a new pipeline. If you have read, write, and edit permissions on a pipeline, you can also provide access to others. You can give access to a team that you're in, or a team that has been marked as 'visible'.

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 agent 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

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

When you enable Teams we’ll create a default team called “Everyone”, 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 via 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.

Once enabled, can I disable Teams?

You can disable teams by deleting all your teams, and then selecting “Disable Teams”.

Member Permissions

Enterprise customers can control user permissions for selected pipeline actions. These permissions can be used both with or without Teams enabled.

User-level permissions are managed by organization administrators, and can be found in the Organization Settings under Member Permissions.

From the Member Permissions page, organization admins can toggle whether or not users can:

  • Create new pipelines
  • Make an existing private pipeline public
  • Create, edit, and delete notification services
  • Create, edit, and delete agent registration tokens
  • Disconnect agents

If your organization has teams enabled, the pipeline creation permissions are managed at a team level. Pipeline creation permission controls can be found on the Teams Settings page. Without teams enabled, the pipeline creation permission control can be found on the Member Permissions page.