# 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
```

### Integrations an app set up

An app installed with the `org` `ci` `admin` permission can create an
organization's integrations. Once an app has set an integration's webhook
secret or API token, GitCafe accepts its Buildkite events and reads its logs
only for repositories the app's installation reaches at that moment. A
pipeline bound to any other repository, including one later removed from the
installation, gets no checks or statuses: GitCafe refuses the delivery, so
Buildkite shows it as failed. Its logs are unavailable too. Uninstalling the
app refuses every repository, until a person replaces the credentials.
Pausing the app refuses every repository until it resumes; events Buildkite
sends while it is paused are not applied, so rebuild after resuming.

An organization administrator lifts this by replacing the webhook secret, and
the API token if one is saved, in the same edit. That does not change who
controls the Buildkite organization the integration names: whoever runs it
there can still see and change its webhook token and builds. If you do not
trust the app with your repositories' checks, add a new integration for a
Buildkite organization you control and move the pipelines to it.

The app can change, disable or remove the integration only while its
installation reaches every repository with a pipeline bound to it
(`CI_INTEGRATION_UNSELECTED_BINDING`). Another app can replace the
credentials only all at once: the webhook secret, and the API token if one is
saved, in the same edit (`CI_INTEGRATION_OTHER_INSTALLATION`). An
organization administrator can always change them.

## Connect a repository's pipeline

1. Open the repository's **Settings → CI** and, under **Buildkite
   pipelines**, choose **Add pipeline**.
2. Choose the integration, enter the Buildkite pipeline slug and a check name
   (the context shown on pull requests).
3. Choose **Add pipeline**. Its builds then appear on the repository's **CI**
   tab beside workflow runs.

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

Transferring a repository to another organization removes its pipelines,
which belong to the old organization's integrations. Add them again from the
new organization; transferring it back does not restore them.

## 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.