Skip to main content
Gitar reads the log of every failing Buildkite build and analyzes it. Buildkite reports a build to the pull request as a status check. That status links to the build, and Gitar fetches the log from the link.

​
Prerequisites

  • Confirm Buildkite reports build results to your pull requests as a status check.
  • Get access to the Buildkite account you want Gitar to read as. A dedicated account such as buildkite-integration@yourcompany.com keeps access working when people leave.

​
Required token scopes

The token must carry all nine scopes below. Buildkite returns a permission error on the first call that is missing one.

​
Setup

1

Create an API access token

  1. Sign in as the user you want Gitar to read as.
  2. Go to API Access Tokens.
  3. Click New API Access Token and name it Gitar.
  4. Select the organization Gitar should read, and select all nine scopes listed above.
  5. Copy the token. Buildkite shows it once.
A token carries its user’s access, so it reads the pipelines that user can see.
2

Enter the token in Gitar

  1. Go to your Gitar organization settings.
  2. Open Integrations.
  3. Find Buildkite and click Connect.
  4. Paste the token into Buildkite API Token.
  5. Click Connect to save. The card’s button changes to Configure once the token validates.
Gitar verifies the token with a test call to Buildkite before it stores it.

​
What Gitar reads

Gitar reads the log of a failing build and passes it to CI failure analysis. It ignores a passing build, and writes nothing back to Buildkite. Results appear as a comment on the pull request. See CI failure analysis.

​
Troubleshooting

Check the pull request for a Buildkite status check.If there is no status, Buildkite is not reporting to your Git provider. Check that the repository is connected to both your Git provider and Buildkite, and that the pipeline is set up in Buildkite.
Check the token against all nine scopes above. A token missing one scope connects and then fails on the call that needs it.Check that you created an API Access Token, and that its user has access to the organization the pipeline belongs to.
Either the token is missing read_build_logs, or its user cannot see the pipeline. Use a token from a user who can already open that build in Buildkite.

​
Security notes

  • Gitar encrypts credentials and stores them in AWS Secrets Manager.
  • Every required scope is read-only. Gitar writes nothing to Buildkite.
  • Prefer a dedicated user’s token over a personal one, so access survives people leaving.
  • To revoke access, delete the token from API Access Tokens.