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, Monorepo CI, 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.

• Monorepo CI: 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.

Monorepo CI 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 Merge Queue Scopes.

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.

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: Monorepo 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

  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.

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.