Buildkite 2FA: how to set up an authenticator app

A Buildkite login reaches your CI/CD pipelines, builds and agents. Two-factor authentication (2FA) adds a code from an authenticator app on top of your password. The one thing to know before you start: Buildkite gives you recovery codes, and if you lose both your authenticator and those codes, its documented way back in is to have your account deleted and to create a new one (Buildkite).

Buildkite's documentation describes one 2FA method, a third-party authenticator app. 2FA is optional for your personal account, but an organization administrator can make it mandatory for everyone in the organization (more on that below). This guide uses Authenticator App - Novaz on iPhone. Any authenticator app works the same way.

How we checked this guide: the Buildkite steps come from Buildkite's own documentation, linked below, which we read on October 21, 2026. We haven't tested them on a Buildkite account, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.

Turn on 2FA with an authenticator app

Buildkite's 2FA tutorial describes these steps in the dashboard (Buildkite):

1. Open the dropdown menu under your profile picture and select Personal Settings.
2. Click Two-Factor Authentication. If a Confirm Password field appears, enter your Buildkite password and continue.
3. Click Setup Two-Factor Authentication.
4. Buildkite shows your recovery codes first. Copy them or download them as a text file, and put them somewhere other than your phone. Then continue.
5. Buildkite shows a barcode (a QR code). In Novaz, tap +, then Scan QR code, and point the camera at it. If the dashboard is open on the same iPhone, take a screenshot and use Choose a photo instead. See scanning a QR code on the same iPhone.
6. If you can't scan it, use the secret key that Buildkite shows below the barcode. In Novaz, tap +, then Enter key manually. Type "Buildkite" as the Service, your email as the Account if you like, and the secret key as the Setup key. See What is a 2FA setup key?
7. Type the 6-digit code from Novaz into the field in Buildkite and click Activate.

When it worked, Personal Settings shows an Enabled badge next to Two-Factor Authentication.

Buildkite says its codes are six digits and change about every 30 seconds, which matches what Novaz makes from a typed key. If Novaz doesn't accept the key you typed, scan the QR code instead.

Your recovery codes are the backup

Buildkite hands you the recovery codes before it even shows the QR code, and its tutorial says to keep them in a safe digital place or on paper and never share them (Buildkite). Take that step seriously. If that phone is gone and Novaz isn't backed up with iCloud backup or a backup file, the recovery codes are how you get back in. The documentation doesn't say how many codes you get, whether each works only once, or how to make a new set. More in 2FA backup codes.

When Buildkite asks for a code

Buildkite asks for the current code when you sign in from a new browser, a new device or a new location (Buildkite).

When your organization enforces 2FA

An organization administrator can require 2FA for every member under Settings > Security, by selecting Enforce Two-factor authentication and then Update Access Control (Buildkite). A few things follow from that:

• Members who haven't set up 2FA lose access to the organization and its pipelines right away. Set it up before the switch is flipped.
• Existing API access tokens keep working, but you can't create new tokens or change existing ones until you've turned on 2FA (Buildkite).
• Organizations that enforce single sign-on (SSO) instead need 2FA enforcement turned off, so the two don't apply together (Buildkite).

If Buildkite rejects your code

Buildkite's documentation has no troubleshooting advice for wrong codes. The most common cause is a phone clock that has drifted. On your iPhone, open Settings > General > Date & Time and turn on Set Automatically. Novaz also warns you when the clock is 15 seconds or more off. Other causes are in Authenticator code not working?

Changing phones

Buildkite says you can reconfigure or turn off 2FA from the Two-Factor Authentication area in Personal Settings (Buildkite). The docs don't describe a phone change, but the safe order is to reconfigure 2FA there while the old phone still gives you codes, and scan the new QR code with Novaz on the new iPhone. Or, if you use Novaz's iCloud backup or a backup file, restore it on the new iPhone and skip the reconfiguring. See How to transfer your authenticator app to a new iPhone.

If you lose your authenticator

Sign in with one of your recovery codes, then set up 2FA again on your new phone.

Without the recovery codes, Buildkite's tutorial offers no way to reset 2FA on the account you have. Its route is (Buildkite):

1. Ask the administrator of your Buildkite organization to remove your account from the organization.
2. Email support@buildkite.com and ask for your account to be deleted.
3. Once it's deleted, create a new account. The tutorial doesn't cover rejoining the organization, so ask your administrator.

The documentation doesn't say what proof support asks for or how long deletion takes. For teams, Buildkite's incident response guide suggests storing an administrator's 2FA secret and recovery codes in a restricted vault (Buildkite). See Lost the phone with your authenticator app?

Turning 2FA off

Go to Personal Settings > Two-Factor Authentication to deactivate it (Buildkite). The tutorial doesn't list the exact buttons. If your organization enforces 2FA, turning it off will cut you off from that organization. After you turn it off, remove the account from Novaz: open it and tap Remove account.

Official Buildkite help

• Two-factor authentication
• Enforce two-factor authentication (2FA)
• Single sign-on support
• Incident response