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.

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.

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.