Scopes with File Patterns

Mergify allows you to define scopes using file patterns to intelligently batch pull requests based on which parts of your monorepo they modify. This approach is simple to set up and works well when your monorepo structure follows clear directory boundaries.

Define scopes in your .mergify.yml configuration file using file patterns:

scopes:
  source:
    files:
      python-api:
        includes:
          - api/**/*.py
          - libs/shared/**/*.py
      frontend:
        includes:
          - web/**/*.js
          - web/**/*.jsx
          - web/**/*.ts
          - web/**/*.tsx
      docs:
        includes:
          - docs/**/*.md
          - docs/**/*.mdx

queue_rules:
  - name: default
    batch_size: 5

In this example:

• Changes to Python files in api/ or libs/shared/ get the python-api scope
• Changes to frontend files in web/ get the frontend scope
• Documentation changes get the docs scope

To wire scopes into GitHub Actions, follow the Monorepo CI GitHub Actions guide. It walks through:

• Adding the gha-mergify-ci workflow step that reads your file-pattern scopes and exposes them as outputs.

• Conditioning downstream jobs (frontend, backend, docs, etc.) on those scope outputs.

• Waiting on the right set of jobs so required checks always report, even when work is skipped.

That guide already includes complete workflow samples, so you do not need to duplicate the config here—just reuse the same scopes you declared above.

The gha-mergify-ci action automatically provides a special merge-queue scope that returns true only when running in a merge queue context (on temporary merge queue branches).

This is useful for:

• Integration tests that only need to run before merging
• End-to-end tests that are expensive and should only run on final batches
• Deployment validation that needs to happen before code reaches the main branch

integration-tests:
  if: ${{ needs.scopes.outputs.merge-queue == 'true' }}
  needs: scopes
  runs-on: ubuntu-22.04
  steps:
    - uses: actions/checkout@v5
    - name: Run expensive integration tests
      run: npm run test:integration

Here’s a real-world example for a monorepo with Python, JavaScript, and Go services:

scopes:
  source:
    files:
      python-api:
        includes:
          - services/api/**/*.py
          - libs/python/**/*.py
      user-service:
        includes:
          - services/users/**/*.go
      frontend:
        includes:
          - apps/web/**/*.{js,jsx,ts,tsx}
      shared-config:
        includes:
          - config/**/*
          - docker/**/*

queue_rules:
  - name: default
    batch_size: 8
    batch_max_wait_time: 5 min

With this configuration:

• PRs affecting only frontend will batch together

• PRs affecting python-api will batch together

• PRs affecting shared-config will batch with everything (since config affects all services)

The gha-mergify-ci action only analyzes files changed by the specific pull request, not files from other PRs in the merge queue batch. This ensures:

• Each PR’s scopes reflect only its own changes
• Batching decisions remain consistent even as the queue changes
• Tests run for the correct scopes regardless of what else is in the batch

GitHub Actions offers path filtering (on.pull_request.paths), but it has critical limitations in merge queue scenarios:

# ❌ Don't use path filtering for merge queues
on:
  pull_request:
    paths:
      - 'api/**'

Problems with path filtering:

• When a job doesn’t run, you can’t distinguish between “filtered out” and “CI failed to start”

• Required status checks fail if jobs are skipped due to filtering

• In merge queues, you don’t want to skip tests on PR2 just because PR1 in the batch modified different files

✅ Use scopes instead:

• Jobs always run but can conditionally skip work based on scope detection
• Status checks always report (success or skipped)
• Merge queue batching respects scope boundaries