# Connect Buildkite

GitCafe shows Buildkite builds on a repository's **CI** tab and as checks on
pull requests. Builds run in Buildkite; GitCafe does not start or schedule
them. Connecting takes two steps: an integration for your account or
organization, then a pipeline for each repository.

## Add the integration

1. Open **Settings → Integrations → Buildkite** for your personal account, or
   **Integrations** in an organization's settings.
2. Enter a display name and your Buildkite organization slug.
3. In Buildkite, add a webhook notification service. Copy its **Token** into
   GitCafe's webhook secret field, and set the service's URL to the receiver
   URL GitCafe shows. Select the `X-Buildkite-Signature` header.
4. Save.

The webhook secret is never shown again. When you rotate the token in
Buildkite, enter the new one in GitCafe.

```sh
cafe integration create acme --type buildkite --name Buildkite \
  --provider-org acme --webhook-secret-env BUILDKITE_WEBHOOK_TOKEN
```

## Connect a repository's pipeline

1. Open the repository's **Settings → CI integrations**.
2. Choose the integration, enter the Buildkite pipeline slug and a check name
   (the context shown on pull requests).
3. Save.

```sh
cafe ci binding create --integration <id> --pipeline my-pipeline --context buildkite
```

## Share job logs

To show jobs and logs in GitCafe, save a Buildkite API token with
`read_builds` and `read_build_logs` in the integration's log access form. Then
turn on **Repository readers can view Buildkite logs** for each pipeline.

Log sharing is off by default. When on, everyone who can read the repository
can read its logs, including anonymous visitors to a public repository.

## Publish results to GitHub

For a repository synchronized with GitHub, you can publish each pipeline's
results to GitHub as checks. Turn on publication in the repository's CI
integration settings. It needs the GitHub App to have Checks read and write
permission on the linked repository.

A run's publication status is shown separately from its result: a run can be
**Successful** while **GitHub publication blocked** means GitHub has not
received it yet. Check the GitHub App's permissions if publication is blocked.