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.
Prerequisites
Section titled Prerequisites-
Buildkite is properly set up and is building your projects. See the Buildkite Documentation for help with setting up Buildkite.
-
Buildkite is configured to report build statuses to GitHub.
-
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
Section titled Job selectionJob 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.
Declare your scopes
Section titled Declare your scopesThe plugin reads the scopes block of your .mergify.yml to know which areas
of the repository map to each scope name:
scopes: source: files: frontend: include: - apps/web/**/* api: include: - services/api/**/* docs: include: - docs/**/*Pipeline outline
Section titled Pipeline outlineA Buildkite pipeline driven by scopes has two parts:
-
Detect scopes using the
mergifyio/mergify-ciplugin. -
Use a dynamic pipeline to conditionally upload only the steps that match the affected scopes.
Static pipeline entry point
Section titled Static pipeline entry pointsteps: - 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 uploadThe 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.
Dynamic pipeline script
Section titled Dynamic pipeline scriptThe script below parses the scope results with
jq, so install it on your Buildkite agents
first.
#!/bin/bashset -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"YAMLfi
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"YAMLfi
if echo "$SCOPES" | jq -e '.docs == "true"' > /dev/null 2>&1; then cat <<'YAML' - label: ":books: Docs build" command: make docsYAMLfi
# 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"YAMLfiMake the script executable:
chmod +x .buildkite/dynamic-pipeline.shIn this pipeline:
-
The
detect-scopesstep calls themergifyio/mergify-ciplugin with thescopesaction, which inspects the pull request diff and stores a JSON map of scopes ("true"or"false") as Buildkite meta-data under the keymergify-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-uploadaction reads that key in either of two shapes: the JSON map thescopesaction 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-processaction to upload test results to CI Insights.
Triggering separate pipelines
Section titled Triggering separate pipelinesIf your monorepo builds live in separate Buildkite pipelines, use trigger steps instead:
#!/bin/bashset -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}"YAMLfi
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}"YAMLfi
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}"YAMLfi
if [ "$(echo "$SCOPES" | jq '[.[] | select(. == "true")] | length')" = "0" ]; then cat <<'YAML' - label: ":fast_forward: No affected scopes" command: "true"YAMLfiEmit a trigger step for every scope you declare: an affected scope with no step of its own is never built.
Adding to the detected scopes
Section titled Adding to the detected scopesOn 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.
Adding extra scopes
Section titled Adding extra scopesSet 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:
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 scopeSet 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.
steps: - label: ":mag: Detect scopes" key: detect-scopes plugins: - mergifyio/mergify-ci#v21: action: scopes all_scopes: trueThe 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?
Thanks for your feedback!