Integrating GitHub Actions with Mergify

GitHub Actions is the CI/CD platform provided by GitHub. Mergify has native integrations for GitHub Actions covering CI Insights, Job Selection, and Merge Queue Scopes. Any GitHub Actions job status can also be referenced from your Mergify conditions via check-success.

1. You’ve set up GitHub Actions in your repository. If you’re new to GitHub Actions, see their official documentation.

2. GitHub Actions is already configured to report job statuses to your pull requests.

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

• CI Insights: collect job metrics, detect flaky tests, and get Slack notifications for CI failures.

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

• Merge Queue Scopes: run only the jobs affected by a batch when processing the merge queue. Examples for Bazel, Nx, and Turborepo are available.

• github_actions action (deprecated): trigger a workflow directly from a Mergify rule.

Job Selection is scopes applied to your workflows. The same scopes block that lets the merge queue batch by scope also tells each job whether it has work to do, so a pull request that only touches the frontend does not pay for the API and docs test suites.

This section covers job skipping on pull requests. For smarter batching or parallel mode in the merge queue, scopes already do that on their own. See Merge Queue Scopes.

Running Buildkite instead? The Buildkite integration covers the same ground. Scopes themselves are CI-agnostic, so for any other provider let us know and see other build tools.

The action 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/**/*

A GitHub Actions workflow driven by scopes has three parts:

1. Detect scopes using the gha-mergify-ci action. Its inputs and outputs are listed in the action reference.

2. Reuse the scope outputs to conditionally run jobs.

3. Publish a final status (for example with a ci-gate job) if you want one check that reflects all the jobs that ran.

name: CI
on:
  pull_request:

jobs:
  detect-scopes:
    runs-on: ubuntu-24.04
    outputs:
      frontend: ${{ fromJSON(steps.scopes.outputs.scopes).frontend }}
      api: ${{ fromJSON(steps.scopes.outputs.scopes).api }}
      docs: ${{ fromJSON(steps.scopes.outputs.scopes).docs }}
    steps:
      - uses: actions/checkout@v5

      - name: Detect scopes
        id: scopes
        uses: Mergifyio/gha-mergify-ci@v25
        with:
          action: scopes
          token: ${{ secrets.MERGIFY_TOKEN }}

  frontend-tests:
    needs: detect-scopes
    if: ${{ needs.detect-scopes.outputs.frontend == 'true' }}
    uses: ./.github/workflows/frontend-tests.yaml
    secrets: inherit

  api-tests:
    needs: detect-scopes
    if: ${{ needs.detect-scopes.outputs.api == 'true' }}
    uses: ./.github/workflows/api-tests.yaml
    secrets: inherit

  docs-tests:
    needs: detect-scopes
    if: ${{ needs.detect-scopes.outputs.docs == 'true' }}
    uses: ./.github/workflows/docs-tests.yaml
    secrets: inherit

  ci-gate:
    if: ${{ !cancelled() }}
    needs:
      - detect-scopes
      - frontend-tests
      - api-tests
      - docs-tests
    runs-on: ubuntu-24.04
    steps:
      - name: Report status
        uses: Mergifyio/gha-mergify-ci@v25
        with:
          action: wait-jobs
          jobs: ${{ toJSON(needs) }}

In this workflow:

• detect-scopes calls gha-mergify-ci with the scopes action, which inspects the pull request diff and returns a JSON map of scopes set to true or false.

• Each job checks the scope it cares about before running, reducing redundant builds.

• The final ci-gate job ensures that the aggregated status reflects the actual CI coverage, even if some jobs were skipped. Keep detect-scopes in its needs: without it, a failed scope detection skips every test job and ci-gate still reports success.

The token on detect-scopes is a Mergify application key with the ci scope, stored as a repository secret; an admin key is rejected. It lets the action send the scopes it detected back to Mergify, which is how Merge Queue Scopes know what a queued pull request affects. wait-jobs needs no token. For pull requests opened by Dependabot, add the same secret to your Dependabot secrets as well.

Mergify also publishes annotations that can be seen in your GitHub Actions jobs summary.

Once ci-gate publishes a single status, add it as a required check in your GitHub branch ruleset so that only pull requests with the relevant jobs executed can merge.