View as Markdown

Integrating Buildkite with Mergify

Run CI Insights, Job Selection, and Scopes on Buildkite.


Buildkite is a CI/CD tool with pipeline orchestration and self-hosted runners. Mergify has native integrations for Buildkite covering CI Insights, Job Selection, and Scopes. Any Buildkite status check reported to GitHub can also be referenced from your Mergify conditions via check-success.

  1. Buildkite is properly set up and is building your projects. See the Buildkite Documentation for help with setting up Buildkite.

  2. Buildkite is configured to report build statuses to GitHub.

  3. The Mergify GitHub App is installed in your repository.

Mergify features for Buildkite

Section titled Mergify features for Buildkite
  • CI Insights: collect Buildkite job metrics, detect flaky tests, and get Slack notifications for CI failures.

  • Job Selection: skip unaffected steps on pull requests to cut CI spend in monorepos.

  • Scopes: batch related pull requests in the merge queue. Examples for Bazel, Nx, and Turborepo are available.

Job Selection is scopes applied to your pipelines. The same scopes block that lets the merge queue batch by scope also tells your pipeline which steps have work to do, so a pull request that only touches the frontend does not pay for the API and docs test suites.

This section wires it into Buildkite; Job Selection explains how it works on any CI. For smarter batching or parallel mode in the merge queue, scopes already do that on their own. See Scopes.

Running GitHub Actions or Jenkins instead? The GitHub Actions and Jenkins integrations cover the same ground. Scopes themselves are CI-agnostic, so for any other provider let us know and see other build tools.

The plugin reads the scopes block of your .mergify.yml to know which areas of the repository map to each scope name:

.mergify.ymlyaml
scopes:
source:
files:
frontend:
include:
- apps/web/**/*
api:
include:
- services/api/**/*
docs:
include:
- docs/**/*

A Buildkite pipeline driven by scopes has two parts:

  1. Detect scopes using the mergifyio/mergify-ci plugin.

  2. Use a dynamic pipeline to conditionally upload only the steps that match the affected scopes.

PR Pull request changes Detect detect-scopes step (mergify-ci plugin) PR->Detect Config Scopes config (.mergify.yml) Config->Detect Frontend frontend-tests (run) Detect->Frontend scope: frontend Docs docs-tests (run) Detect->Docs scope: docs API api-tests (skipped) Detect->API scope: api (false) PR Pull request changes Detect detect-scopes step (mergify-ci plugin) PR->Detect Config Scopes config (.mergify.yml) Config->Detect Frontend frontend-tests (run) Detect->Frontend scope: frontend Docs docs-tests (run) Detect->Docs scope: docs API api-tests (skipped) Detect->API scope: api (false)
detect-scopes runs first, and each test step runs only when its scope changed
.buildkite/pipeline.ymlyaml
steps:
- label: ":mag: Detect scopes"
key: detect-scopes
plugins:
- mergifyio/mergify-ci#v21:
action: scopes
- label: ":pipeline: Upload conditional steps"
depends_on: detect-scopes
command: .buildkite/dynamic-pipeline.sh | buildkite-agent pipeline upload

The plugin reads your application key from MERGIFY_TOKEN in the agent’s environment. The key needs CI Reporting, which a key granted Every resource does not hold. Detection is local, so the meta-data this step writes, and the step skipping below that reads it, work without a token. What a missing token costs is the upload: the plugin logs a warning and sends nothing, so the merge queue never sees the scopes.

The test steps the dynamic pipeline emits need the token too, and they can run on different agents from the one that detected the scopes.

The script below parses the scope results with jq, so install it on your Buildkite agents first.

.buildkite/dynamic-pipeline.shbash
#!/bin/bash
set -euo pipefail
SCOPES=$(buildkite-agent meta-data get "mergify-ci.scopes" --default '{}')
echo "steps:"
if echo "$SCOPES" | jq -e '.frontend == "true"' > /dev/null 2>&1; then
cat <<'YAML'
- label: ":react: Frontend tests"
command: npm test
plugins:
- mergifyio/mergify-ci#v21:
action: junit-process
report_path: "junit.xml"
YAML
fi
if echo "$SCOPES" | jq -e '.api == "true"' > /dev/null 2>&1; then
cat <<'YAML'
- label: ":gear: API tests"
command: pytest tests/api/
plugins:
- mergifyio/mergify-ci#v21:
action: junit-process
report_path: "reports/*.xml"
YAML
fi
if echo "$SCOPES" | jq -e '.docs == "true"' > /dev/null 2>&1; then
cat <<'YAML'
- label: ":books: Docs build"
command: make docs
YAML
fi
# Buildkite rejects a pipeline with no steps, so emit a no-op when a pull
# request touches nothing in any scope.
if [ "$(echo "$SCOPES" | jq '[.[] | select(. == "true")] | length')" = "0" ]; then
cat <<'YAML'
- label: ":fast_forward: No affected scopes"
command: "true"
YAML
fi

Make the script executable:

Terminal windowbash
chmod +x .buildkite/dynamic-pipeline.sh

In this pipeline:

  • The detect-scopes step calls the mergifyio/mergify-ci plugin with the scopes action, which inspects the pull request diff and stores a JSON map of scopes ("true" or "false") as Buildkite meta-data under the key mergify-ci.scopes. It also annotates the build with the scopes it found, so they are readable on the build page without opening the step log.

    The scopes-upload action reads that key in either of two shapes: the JSON map the scopes action writes, where it takes the names whose value is "true"; or a comma-separated list of scope names. The per-tool guides, such as Turborepo, write the comma-separated form from their own detection step, so the two styles are interchangeable rather than alternatives you have to choose between.

  • The dynamic pipeline script reads the scopes meta-data and only emits the steps for scopes that are "true", so unaffected steps are skipped entirely.

  • Each test step can optionally use the junit-process action to upload test results to CI Insights.

If your monorepo builds live in separate Buildkite pipelines, use trigger steps instead:

.buildkite/dynamic-pipeline.shbash
#!/bin/bash
set -euo pipefail
SCOPES=$(buildkite-agent meta-data get "mergify-ci.scopes" --default '{}')
echo "steps:"
if echo "$SCOPES" | jq -e '.frontend == "true"' > /dev/null 2>&1; then
cat <<'YAML'
- trigger: "frontend-pipeline"
label: ":react: Trigger frontend pipeline"
build:
branch: "${BUILDKITE_BRANCH}"
commit: "${BUILDKITE_COMMIT}"
YAML
fi
if echo "$SCOPES" | jq -e '.api == "true"' > /dev/null 2>&1; then
cat <<'YAML'
- trigger: "api-pipeline"
label: ":gear: Trigger API pipeline"
build:
branch: "${BUILDKITE_BRANCH}"
commit: "${BUILDKITE_COMMIT}"
YAML
fi
if echo "$SCOPES" | jq -e '.docs == "true"' > /dev/null 2>&1; then
cat <<'YAML'
- trigger: "docs-pipeline"
label: ":books: Trigger docs pipeline"
build:
branch: "${BUILDKITE_BRANCH}"
commit: "${BUILDKITE_COMMIT}"
YAML
fi
if [ "$(echo "$SCOPES" | jq '[.[] | select(. == "true")] | length')" = "0" ]; then
cat <<'YAML'
- label: ":fast_forward: No affected scopes"
command: "true"
YAML
fi

Emit a trigger step for every scope you declare: an affected scope with no step of its own is never built.

On a pull request build, the scopes step also sends the scopes it detected to Mergify, reported for the pull request’s head commit. Two plugin options add to that report, which counts when your scopes source declares manual beside files.

Set scopes to a comma-separated list of scope names, such as the scopes your build tool knows on top of the file patterns. They are added to the scopes detected from the changed files and sent in the same report:

yaml
steps:
- label: ":mag: Detect scopes"
key: detect-scopes
plugins:
- mergifyio/mergify-ci#v21:
action: scopes
scopes: "lib-a,lib-b"

Send them from this step rather than from a scopes-upload step of their own: a report replaces the previous one for the same commit, so whichever step reports last is the only one the merge queue sees.

The extra scopes only go to Mergify. The mergify-ci.scopes meta-data keeps the detected scopes only, so the dynamic pipeline script does not see them.

Plugin options are fixed when the pipeline is uploaded. When a command computes the scopes, have it write this step and upload it with buildkite-agent pipeline upload.

Declaring a pull request impacts every scope

Section titled Declaring a pull request impacts every scope

Set all_scopes: true to declare that the pull request impacts all scopes. The merge queue treats such a pull request as a barrier: it conflicts with every scope, so it is never batched or merged in parallel with other pull requests.

yaml
steps:
- label: ":mag: Detect scopes"
key: detect-scopes
plugins:
- mergifyio/mergify-ci#v21:
action: scopes
all_scopes: true

The concrete scopes are still sent with the flag. all_scopes works on the scopes-upload action too, which then needs no concrete scope. Like scopes, it is fixed when the pipeline is uploaded, so set it on a step that a command uploads only for the pull requests that need it.

Was this page helpful?