Single sign-on with GitHub
You can use GitHub as an SSO provider for your Buildkite organization. To complete this tutorial, you need admin privileges for both the Buildkite organization and your GitHub organization.
Step 1. Link your Buildkite organization to your GitHub organization
Set up the Buildkite GitHub Application for your GitHub organization. You need to install Buildkite for the GitHub organization that you want to connect to Buildkite as an SSO provider.
In your Buildkite organization Settings' Repository Providers menu item, connect your GitHub user account to Buildkite. Grant Buildkite the permission to verify your GitHub identity.
Step 2. Create an SSO provider
- In your Buildkite organization Settings' Single Sign On menu item, choose the GitHub provider:
- Enter the name of your GitHub organization.
- Click Create Provider.
Step 3. Perform a test login
Follow the instructions on the provider page to perform a test login. Performing a test login verifies that SSO is working correctly before you activate it for your organization members.
Step 4. Enable the new SSO provider
Once you've performed a test login you can enable your provider. Activating SSO will not force a log out of existing users, but will cause all new or expired sessions to authorize through GitHub before organization data can be accessed.
If you need to edit or update your GitHub provider settings at any time, you will need to disable the SSO provider first.
After you've enabled GitHub as the SSO provider for your Buildkite organization, new and expired users will need to log in through GitHub by visiting buildkite.com/sso/your-organization-name. They will be asked to provide their email address, and a sign-in link will be emailed to them.
Sending the sign-in link by email is an additional security and privacy measure, as a user can be a member of several Buildkite organizations. If the names of such Buildkite organizations themselves contain information – for example, buildkite.com/sso/flyingcar or buildkite.com/sso/aliens, disclosing a list of such organizations to somebody who only knows an email address could leak sensitive information.
SAML user attributes
Buildkite accepts a subset of the SAML attributes from identity providers. The accepted attributes are:
| Attribute | Description |
|---|---|
admin
|
A boolean value that describes whether the user should be provisioned with admin permissions Example: true |
email
|
A string of the user's email address Example: "person@company.com" |
name
|
A string of the user's full name Example: "Han Solo" |
teams
|
A comma separated list of team UUIDs. A team's UUID can be found on the Team Settings page in Buildkite. Example: a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa,b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee
|
When using the teams attribute, you can also specify roles. The maintainer or member role can be appended to the team UUID.
For example, the following code will specify the member role for the first team and the maintainer role for the second team:
teams="b5bbbbbb-3aaa-dd1d-aaa1-eee4eee6eeee/member, a1aaaa1a-b2bb-cccc-d4dd-aa2aaa6aaaaa/maintainer"