Two-Factor Authentication

Two-factor authentication (2FA) can be added to your Buildkite account to provide an additional layer of security and to make sure your builds are safe even if your login credentials are compromised (exposed or stolen).

Once 2FA is enabled on your Buildkite account, the only way to log in to your account is by knowing both your password and a unique code generated by a third-party application such as 1Password, OTP Auth, Duo Mobile, Authy, or Google Authenticator.

Setting up two-factor authentication

You can set up two-factor authentication in the Buildkite dashboard. To do it, select Personal Settings in the drop-down menu under your profile picture.

Screenshot of Personal Settings Button

Next, navigate to the Two-Factor Authentication tab and click it (you may be asked to enter your password in the Confirm Password field).

Screenshot of Password Confirmation

Enter your Buildkite account password and proceed.
Screenshot of Accessing Two-Factor Authentication

Click the Setup Two-Factor Authentication button to start securing your Buildkite account.

Screenshot of Setup Button for Two-Factor Authentication

Step 1: Store Recovery Codes

You will need them to restore access to your account if you lose access to your authenticator application. Use the buttons to either copy the codes to Clipboard or download them as a text file. Keep your recovery codes in a safe digital space or print them out and hide them well. Never share your recovery codes.

Screenshot of Recovery Codes for Two-Factor Authentication

Saved your recovery codes and proceed.

Step 2: Configure Authenticator Application

To activate two-factor authentication, scan the barcode that appears in the Buildkite dashboard with the authenticator application of your choice. If you cannot scan the barcode, you can use the secret key below the barcode.

After you've scanned the barcode or activated the authenticator application using the secret key, Buildkite will appear on the list of accounts registered in that application. Your authenticator will provide a new randomly generated six-digit code (your One Time Pass) roughly every 30 seconds. Enter this code into the corresponding field in the Buildkite app and click Activate.

Screenshot of Barcode and Secret Key for Two-Factor Authenticator

Congratulations! You have now successfully enabled the two-factor authentication for your Buildkite account. This will be confirmed by an 'Enabled' badge next to the Two-Factor Authentication option in your Personal Settings.

Screenshot of Two-Factor Authentication Enabled Badge

Next time you try to log into your Buildkite account from a new browser, device, or location, you will be asked to enter the current One Time Password provided by your authentication app.

You can always reconfigure or deactivate the 2FA if you need to. This can be done in the Two-Factor Authentication tab in Personal Settings for your Buildkite account in the dashboard.

Recovering access after losing recovery codes

If you are locked out of your Buildkite account with two-factor authorization enabled and have no recovery codes, there is still a way to regain access to your Buildkite builds.

You need to ask the administrator of your Buildkite organization to remove your account. Next, contact support@buildkite.com and ask your account to be deleted. Once it’s deleted, you can create a new one.

Enforcing two-factor authentication for the whole organization

Currently, it’s not possible to enforce 2FA in Buildkite for members of an organization. However, you can check the current 2FA status via the User Settings page for your organization. You’ll see a 2FA badge next to the users who have it enabled.

Checking Two-Factor Authentication Status of a User

If conducting a regular audit is not enough, many SSO providers can enforce 2FA. In turn, Buildkite can enforce SSO for members of an organization. If you’re already using an SSO provider this may be a solution. Read more about using SSO with Buildkite.