Configuration

Step 1: Create a Buildkite API Token

1. In Buildkite, go to Personal Settings → API Access Tokens.

2. Click New API Access Token.

3. Name it (e.g., nullify-ci-feedback).

4. Select your organization.

5. Enable the following scopes:

   • read_builds

   • read_build_logs

6. Click Create Token and copy the token value.

The token is only shown once. Store it securely before closing the page.

Step 2: Configure in Nullify

1. In the Nullify dashboard, go to Configure → Connectors.

2. Find the Buildkite card and click Connect Buildkite.

3. Enter your Organization slug (the URL-friendly name from buildkite.com/<your-org>).

4. Paste the API token from Step 1.

5. Click Save.

The connector status should show Active with your organization name.

Step 3: Configure Buildkite GitHub Integration

For Nullify to receive build results, Buildkite must report CI status to GitHub via commit statuses.

1. In Buildkite, go to Organization Settings → Repository Providers → GitHub.

2. Ensure the Buildkite GitHub App is installed (not the legacy OAuth integration).

3. In your pipeline settings, verify Publish commit statuses is enabled.

Step 4: GitHub App Permissions

The Nullify GitHub App must be configured to receive commit status events from GitHub. This requires two changes by a Nullify administrator:

1. Repository permission: Set Commit statuses to Read-only.

2. Event subscription: Enable the Status event.

After these changes are made, each GitHub organization owner where the Nullify app is installed must accept the updated permission request. GitHub sends a notification email and shows a banner in the organization's installed apps page.

Until the organization owner accepts the permission change, Nullify will not receive Buildkite build status events for that organization.

Step 5: Verify

1. Trigger a Buildkite build on a pull request (push a commit to an open PR).

2. Confirm the build status appears on the GitHub pull request.

3. If the build fails, Nullify will automatically fetch the logs and use them for autofix iteration.

Troubleshooting

Issue	Solution
"Invalid API token"	Verify the token exists in Buildkite and hasn't been revoked.
"Organization not found"	Check the org slug matches your Buildkite URL exactly.
No build status on GitHub PR	Ensure the Buildkite GitHub App is installed and the pipeline has "Publish commit statuses" enabled.
Logs not fetched	Verify the API token has read_build_logs scope.

Token Rotation

To rotate the Buildkite API token:

1. Create a new token in Buildkite (Step 1 above).

2. Update the token in Nullify via Configure → Connectors → Buildkite → Update.

3. Revoke the old token in Buildkite.

Removing the Integration

To disconnect Buildkite from Nullify:

1. Go to Configure → Connectors → Buildkite.

2. Click the delete button.

This removes the stored token and org slug. Buildkite pipelines continue to run independently.