Mergify

View saved version →

---
name: mergify-ci
description: Use Mergify CI commands to upload JUnit test results, detect git references, manage CI scopes, and retrieve merge queue metadata. ALWAYS use this skill when working with CI pipelines, test result uploads, quarantine, scopes detection, or merge queue CI context. Triggers on CI, JUnit, test results, quarantine, scopes, git refs, CI insights.
---

# Mergify CI Commands

## Overview

The `mergify ci` command group provides tools for CI pipelines: uploading JUnit test results to Mergify CI Insights, detecting git references for diff-based operations, managing CI scopes for selective testing, and retrieving merge queue batch metadata.

## Commands

```bash
mergify ci junit-process FILES...         # Upload JUnit XML + evaluate quarantine (primary command)
mergify ci junit-upload FILES...          # (Deprecated) Use junit-process instead
mergify ci git-refs                       # Detect base/head git references for the current PR
mergify ci scopes --config PATH           # Detect scopes impacted by changed files
mergify ci scopes-send -s SCOPE           # Report scopes against the pull request's head commit
mergify ci queue-info                     # Output the current build's merge queue batch metadata (from the git note)
mergify tests show NAME...                # Look up tests by name and print health, ratios, last failure
mergify tests quarantines add NAME        # Add a test to the CI Insights quarantine
mergify tests quarantines remove NAME     # Remove a test from the CI Insights quarantine
mergify tests quarantines get NAME        # Print a single quarantine by test name or id
mergify tests quarantines list            # List the tests currently in the CI Insights quarantine
```

## Authentication

Two classes of Mergify application key, both minted in the dashboard:

| Key | Reaches |
| --- | --- |
| `ci` | What a CI job does: trace upload, `scopes-send`, quarantine *evaluation* (`junit-process`) and the quarantine *list*. |
| `admin` | Everything a `ci` key reaches, plus reading test health and mutating the quarantine. |

Every endpoint below that refuses a `ci` key accepts a GitHub PAT instead.
`GITHUB_TOKEN` inside GitHub Actions is *not* a PAT — it is the ephemeral
installation token — so do not reach for it to clear one of these `403`s.

The split follows the endpoint each command calls: reads of test health and
writes to the quarantine are a person inspecting or overriding a repository,
not something a pipeline does, so they are outside what a `ci` key carries.
Per command:

| Command | `ci` key |
| --- | --- |
| `ci junit-process`, `ci junit-upload`, `ci scopes-send` | yes |
| `tests quarantines list`, `tests quarantines get` | yes — both read the quarantine list |
| `tests show` | **no** — `403` |
| `tests quarantines add`, `tests quarantines remove` | **no** — `403` |

`ci git-refs`, `ci scopes` and `ci queue-info` are evaluated locally and need
no token at all.

## JUnit Processing (`junit-process`)

The primary CI command. Parses JUnit XML reports, checks quarantine status for failing tests, uploads results to Mergify CI Insights, and determines the final CI exit code.

```bash
mergify ci junit-process \
  --token "$MERGIFY_TOKEN" \
  --repository owner/repo \
  --tests-target-branch main \
  path/to/junit-results.xml
```

`FILES` can be individual paths or quoted glob patterns (e.g. `'reports/**/*.xml'`). Always quote the pattern so Mergify expands it rather than the shell — this is the recommended approach for large, sharded test suites.

**Key options:**
- `--token` / `-t` (env: `MERGIFY_TOKEN`) -- CI Insights application key
- `--repository` / `-r` -- Repository full name (auto-detected in GitHub Actions)
- `--tests-target-branch` / `-ttb` -- Branch used for quarantine evaluation. Auto-detected per CI provider: GitHub Actions (`GITHUB_BASE_REF` → `GITHUB_HEAD_REF` → `GITHUB_REF_NAME` → `GITHUB_REF`), Buildkite (`BUILDKITE_PULL_REQUEST_BASE_BRANCH` → `BUILDKITE_BRANCH`), Circle

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mergify-config
description: Use Mergify config commands to validate configuration files, simulate Mergify actions, and write Mergify configuration. ALWAYS use this skill when validating, writing, editing, or simulating Mergify config. Triggers on config validate, config simulate, mergify configuration, mergify.yml, .mergify.yml, merge queue config, workflow rules, conditions.
---

# Mergify Configuration Management

## Overview

The `mergify config` command group provides tools for validating Mergify configuration files against the official schema and simulating what Mergify would do on a specific pull request using a local configuration file.

## Commands

```bash
mergify config validate                              # Validate the configuration file
mergify config simulate PULL_REQUEST_URL             # Simulate actions on a PR
```

## Configuration File Detection

Mergify CLI auto-detects the configuration file from standard locations:
- `.mergify.yml`
- `.mergify/config.yml`
- `.github/mergify.yml`

Override with `--config-file` / `-f`:
```bash
mergify config -f path/to/config.yml validate
```

## Validating Configuration (`validate`)

Validates the Mergify configuration file against the official JSON schema fetched from `https://docs.mergify.com/mergify-configuration-schema.json`.

```bash
# Validate auto-detected config file
mergify config validate

# Validate a specific file
mergify config -f .mergify.yml validate
```

**Output:**
- If valid: prints a success message and exits with code 0
- If invalid: prints the number of errors and each error's path and message, then exits with code 1

**Use in CI:**
```yaml
- name: Validate Mergify config
  run: mergify config validate
```

## Simulating Actions (`simulate`)

Simulates what Mergify would do on a specific pull request using the local configuration file. This lets you test configuration changes before committing them.

```bash
mergify config simulate https://github.com/owner/repo/pull/123
```

**Required arguments:**
- `PULL_REQUEST_URL` -- Full GitHub URL of the pull request to simulate against

**Options:**
- `--token` / `-t` (env: `MERGIFY_TOKEN`) -- Mergify credential. Falls back to the credential `mergify auth login` stored, then to `GITHUB_TOKEN` / `gh auth token`, both deprecated for the Mergify API.
- `--api-url` / `-u` (env: `MERGIFY_API_URL`) -- Mergify API URL (default: `https://api.mergify.com`)

**Output:** Shows a title and detailed Markdown summary of what actions Mergify would take on the PR with the local configuration.

## Writing and Editing Configuration

When helping a user write, edit, or understand a Mergify configuration file,
**always fetch the relevant documentation pages first**. Do not rely on
memorized knowledge -- the configuration format, available actions, and
conditions syntax evolve over time.

### Documentation index

Fetch `https://docs.mergify.com/llms.txt` to get the full documentation index
with all available pages and their descriptions.

### Key reference pages

Fetch the pages relevant to the user's request before writing any configuration:

| Topic | URL |
|-------|-----|
| File format and structure | `https://docs.mergify.com/configuration/file-format` |
| Conditions syntax and attributes | `https://docs.mergify.com/configuration/conditions` |
| Data types (duration, templates) | `https://docs.mergify.com/configuration/data-types` |
| Configuration sharing and reuse | `https://docs.mergify.com/configuration/sharing` |
| Workflow automation overview | `https://docs.mergify.com/workflow` |
| All available actions | `https://docs.mergify.com/workflow/actions` |
| Writing your first rule | `https://docs.mergify.com/workflow/writing-your-first-rule` |
| Merge queue rules | `https://docs.mergify.com/merge-queue/rules` |
| Merge queue setup | `https://docs.mergify.com/merge-queue/setup` |
| Queue priority rules | `https://docs.mergify.com/merge-queue/priority` |
| Merge protections | `https://docs.mergify.com/merge-protecti

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mergify-events
description: Use `mergify events` to browse the Mergify activity log — every event Mergify recorded for a repository or one pull request (queue enters/leaves, merges, commands, CI Insights, freezes), as a human timeline or JSON. ALWAYS use this skill when investigating what Mergify did to a PR or repository and when, reconstructing a pull request's merge-queue lifecycle, auditing Mergify actions, or filtering events by type. Triggers on activity log, event log, events, what did Mergify do, queue lifecycle, queue history, event timeline, event_type, action.queue.
---

# Mergify Events

## Overview

`mergify events` lists the repository's Mergify activity log as a timeline — the ~45 event types the engine records: the `action.queue.*` lifecycle, workflow actions (`action.merge`, `action.rebase`, `action.label`, …), user commands (`command.queue`, `command.dequeue`), `ci_insights.*`, queue pauses, and scheduled freezes. One command over filters; there is deliberately no command per event type.

```bash
mergify events                                  # whole repo, last 24h
mergify events --pr 1740                        # one PR's events, last 24h
mergify events --pr 1740 --since 7d             # wider window (s/m/h/d/w, max 90d)
mergify events --type action.queue.leave --type command.queue   # filter, repeatable
mergify events --pr 1740 --json                 # raw events, newest first
mergify events --limit 20                       # newest 20 only (the header says so)
```

## The window rule (the one thing to get right)

Every result covers an **explicit time window**, stated in the header and in the empty-case message:

```
PR #1740 · 6 events · 2026-07-29 21:00 → 2026-07-30 21:00 UTC
```

- Default window: the **last 24 hours**. A PR dequeued last week shows **nothing** in the default window — that is "nothing in the last 24h", never "no history".
- Retention is **90 days**; `--since 90d` is the widest useful window. Anything wider is rejected up front with the fix in the message.
- An empty result names the window: `No events for PR #1740 between <from> and <to> UTC.` If you did not search the full retention yet, widen with `--since 90d` before concluding anything.

## Reading the timeline

Oldest first (it reads down the page), with a summary per event where the metadata carries one:

```
  2026-07-30
  14:02  action.queue.enter         default
  14:31  action.queue.checks_start  default · draft PR #1801
  15:04  action.queue.checks_end    CHECKS_RETRIED
  15:04  action.queue.leave         CHECKS_FAILED
  15:12  command.queue              @jd
```

Caveat that prevents a real mistake: an abort code on **`action.queue.checks_end`** (`PR_AHEAD_DEQUEUED`, `MERGE_QUEUE_RESET`, `CHECKS_RETRIED`, …) means the *checks* were interrupted while the PR **stayed queued**. Only **`action.queue.leave`** means the PR left the queue — and its `merged: true` variant means it left by merging. Do not requeue a PR over a `checks_end` event.

## JSON contract

`--json` emits one document; `events` are the API's raw objects (unknown fields intact), **newest first**:

```json
{
  "repository": "owner/repo",
  "pull_request": 1740,
  "received_from": "2026-07-29T21:00:00+00:00",
  "received_to": "2026-07-30T21:00:00+00:00",
  "size": 6,
  "events": [ { "id": 123, "type": "action.queue.leave", "received_at": "…", "metadata": { "…": "…" } } ]
}
```

The window is echoed so an empty `events` is self-describing. Filter with `jq` on `.events[].type` and `.events[].metadata`.

## When to use something else

- **"Why was this PR dequeued?"** — `mergify queue show <PR>` (the `mergify-merge-queue` skill) is the dedicated answer: it renders the last leave event with the reason, the failing checks' job URLs, and the head-SHA staleness check. `mergify events` is for the *whole* trail or for non-queue events.
- **Raw API access** (CLI not installed, or a token refused the log): `GET /v1/repos/{owner}/{repo}/logs` — same data; always pas

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mergify-merge-protections
description: Use Mergify merge protections to control when PRs merge — PR dependencies (Depends-On header), delayed merges (Merge-After header), and scheduled freezes (CLI). ALWAYS use this skill when managing merge freezes, deployment windows, temporarily blocking merges, setting up PR dependencies, blocking a PR on another PR, coordinating cross-repo merges, scheduling a merge for a specific time, or adding Depends-On or Merge-After headers to PRs. Triggers on freeze, scheduled freeze, merge freeze, deployment freeze, halt merges, depends on, dependency, block merge, merge after, merge later, schedule merge, delayed merge, cross-repo, merge protection.
---

# Mergify Merge Protections

Merge protections control when PRs are allowed to merge:

| Protection | Scope | How |
|------------|-------|-----|
| **Depends-On** | Per-PR dependency chain | `Depends-On:` header in PR body |
| **Merge-After** | Per-PR time gate | `Merge-After:` header in PR body |
| **Scheduled Freezes** | Repository-wide or conditional | CLI commands (`mergify freeze`) |

`Depends-On` and `Merge-After` are built-in — just add the header to the PR description (or commit message body when using `mergify stack push`) and Mergify enforces them automatically, no `.mergify.yml` configuration needed. Freezes are managed via CLI commands.

## Depends-On

Block a PR from merging until one or more other PRs are merged first.

### Syntax

Add one or more `Depends-On:` lines to the PR body:

```
Depends-On: #123
Depends-On: https://github.com/org/other-repo/pull/456
Depends-On: org/other-repo#789
```

All three formats are supported — use `#NNN` for same-repo, full URL or `org/repo#NNN` for cross-repo.

### Rules

- All referenced PRs must be in repositories with Mergify enabled
- All referenced PRs must belong to the same GitHub organization
- Circular dependencies and self-references are silently ignored
- Multiple `Depends-On:` lines are allowed (one per line)

### With `mergify stack push`

The stack tool **automatically** adds `Depends-On: #NNN` between consecutive PRs in a stack. For dependencies *outside* the stack (cross-repo or unrelated PRs), add the header manually to the **commit message body** — it will be copied to the PR description on push.

### When to suggest

- Feature spanning multiple repos (e.g., API change + client update)
- Schema migration must merge before application code
- Shared library update must land before consumers

## Merge-After

Postpone merging until a specified date and time.

### Syntax

Add a `Merge-After:` line to the PR body:

```
Merge-After: 2025-09-01T09:00:00Z
```

### Supported timestamp formats (ISO 8601)

```
Merge-After: 2025-09-01                          # date only (midnight UTC)
Merge-After: 2025-09-01T09:00:00                 # no timezone (assumed UTC)
Merge-After: 2025-09-01T09:00:00Z                # explicit UTC
Merge-After: 2025-09-01T09:00:00+02:00           # with UTC offset
Merge-After: 2025-09-01T09:00:00[Europe/Paris]   # with IANA timezone
```

If no timezone is specified, UTC is assumed.

### When to suggest

- Coordinated release: multiple PRs should merge together at a specific time
- Merge during a maintenance window or off-peak hours
- Embargo: PR is ready but should not ship before a date

### Combining Depends-On and Merge-After

Both headers can be used together on the same PR:

```
This PR updates the billing API to support the new pricing model.

Depends-On: org/billing-service#42
Merge-After: 2025-06-15T10:00:00[US/Eastern]
```

The PR will not merge until PR #42 in `billing-service` is merged **and** the specified time has passed.

## Scheduled Freezes

Scheduled freezes temporarily halt merging of pull requests matching specific conditions. Use them for deployment windows, incident response, maintenance periods, or any situation where merges should be paused.

## Commands

```bash
mergify freeze list                       # List all scheduled freezes
me

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mergify-merge-queue
description: Use Mergify merge queue to queue/dequeue PRs, to monitor and inspect the queue, and to diagnose a dequeued PR — whether it is queued, why it was dequeued, where its CI failure is, and what to do next. ALWAYS use this skill when queuing or dequeuing a PR, checking queue status, investigating PR merge state, finding out why a PR left the queue, pausing/unpausing the queue, or debugging merge failures. Triggers on queue a PR, requeue, dequeue, dequeued, why was my PR dequeued, dequeue reason, merge queue, queue status, queue pause, queue show, pause, unpause, frozen, bisecting, batch, CI checks, CHECKS_FAILED, PULL_REQUEST_UPDATED.
---

# Mergify Merge Queue

## Overview

The merge queue serializes PR merges, running CI on temporary merge commits to catch integration failures before they reach the target branch. Use comments on the PR to queue/dequeue it, and the CLI to monitor queue state, inspect individual PRs, and manage the queue.

`mergify queue show <PR>` reports on a PR that is **no longer** in the queue too — whether it was dequeued, merged by the queue, or never queued, and why — so start there for a PR that vanished from the queue. See [Diagnosing a dequeued PR](#diagnosing-a-dequeued-pr); the GitHub-side surfaces documented there are the fallback for when the CLI cannot read the activity log.

## Queuing and Dequeuing a PR

Queue, dequeue, and requeue actions are driven by **comments on the pull request**, not the CLI:

| Comment | Effect |
|---------|--------|
| `@mergifyio queue` | Add the PR to the merge queue (also use to **requeue** a PR that was dequeued) |
| `@mergifyio dequeue` | Remove (dequeue) the PR from the merge queue |

`@mergifyio requeue` is accepted, but it is a deprecated alias that runs the same command as `@mergifyio queue` — there is no separate requeue behavior. Post `@mergifyio queue`.

When Mergify processes the comment, it adds a 👍 (thumbs up) reaction to the comment to acknowledge receipt. After queuing, use `mergify queue show <PR_NUMBER>` to watch the PR's status as it progresses through the queue.

## Commands

```bash
mergify queue status                 # Show queue status (batches, waiting PRs)
mergify queue status --branch main   # Filter by branch
mergify queue status --json          # Machine-readable JSON output
mergify queue show <PR_NUMBER>       # Detailed state of a PR in the queue
mergify queue show <PR_NUMBER> -v    # Full checks table and conditions tree
mergify queue show <PR_NUMBER> --json # Machine-readable JSON output
mergify queue pause --reason "..."   # Pause the queue (requires reason)
mergify queue unpause                # Resume the queue
```

That is the whole `queue` group: `status`, `show`, `pause`, `unpause`. There is no subcommand for dequeuing a PR — the dequeue reason comes from `queue show` on a PR that has left the queue, not from a flag. For the full queue *trail* (every enter / checks / leave event, not just the last exit), use `mergify events --pr <PR> --since 90d` — see the `mergify-events` skill.

## Is the PR queued, dequeued, or never queued?

Start here — the rest of the workflow branches on this answer.

`mergify queue show <PR>` answers all four cases. A PR with no queue entry is a normal answer, not an error: the command prints a notice and **exits 0** in every case below.

| `queue show` result | Meaning |
|---|---|
| `PR #N` block with position / CI state | The PR **is in the queue** |
| `PR #N was dequeued <when>` + a `Dequeue code` | It **left the queue without merging** — see the reason table |
| `PR #N was merged by the merge queue <when>` | It left the queue **by merging**. Not a dequeue |
| `PR #N is not in the merge queue` | **No queue activity in the retained window** — never queued, aged out, or not a real PR number |

Under `--json`, a PR that is not currently queued carries `queued: false` plus a `dequeued` discriminator:

```bash
mergify queue show 1234 --json | jq -e '.queued == false' >/

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: mergify-stack
description: Use Mergify stacks for git push, commit, branch, and PR creation. ALWAYS use this skill when pushing code, creating commits, creating branches, or creating PRs. Triggers on push, commit, branch, PR, pull request, stack, stacked, git, rebase, checkout, reorder, move, sync, amend, note, revision history.
---

# Mergify Stack Workflow

## Stack Philosophy

A branch is a stack. Keep stacks short and focused:
- A stack should only contain commits that **depend on each other**
- Rationale: longer stacks take longer to merge

**Proactive stack management:**
- If an existing stack can be split into independent stacks, offer to do so
- When asked to do something new: if it can be done on a separate branch, either do so or ask if in doubt
- Default to creating a new branch for unrelated changes

## Core Conventions

- **Push**: Use `mergify stack push` (never `git push`)
- **Fixes**: Use `git commit --amend` (never create new commits to fix issues)
- **Amend notes**: When amending a commit that already has a PR (i.e. has been pushed), attach a `mergify stack note` BEFORE `mergify stack push` to record *why* the commit was amended. The note appears in the PR's "Revision history" comment and JSON marker, so reviewers can see the reason without diffing.
- **Mid-stack fixes**: Stash any local changes first (`git stash -u`), then use `mergify stack edit <SHA-or-Change-Id-prefix>` to pause the rebase at the target commit. Amend it with `git commit --amend`, then `git rebase --continue`, then `mergify stack push`, then `git stash pop`. Non-interactive — never use `git rebase -i` for this. (Calling `mergify stack edit` with no argument falls back to a fully interactive `git rebase -i` and will hang in agent contexts — always pass a commit prefix.)
- **Reordering**: Stash any local changes first (`git stash -u`), then use `mergify stack reorder` (list all commits in desired order) or `mergify stack move` (move a single commit) instead of manual `git rebase -i` — non-interactive and avoids `GIT_SEQUENCE_EDITOR` quoting issues
- **Fixup**: Stash any local changes first (`git stash -u`), then use `mergify stack fixup <SHA>...` to fold a commit into its parent (drops the listed commit's message). Non-interactive — never use `git rebase -i` for this.
- **Squash**: Stash any local changes first (`git stash -u`), then use `mergify stack squash SRC... into TARGET [-m "msg"]` to combine multiple commits into one, with an optional custom message. Non-interactive — never use `git rebase -i` for this.
- **Reword**: Stash any local changes first (`git stash -u`), then use `mergify stack reword <SHA> -m "new message"` to change a commit's message in place. Non-interactive when `-m` is given — never use `git rebase -i` for this.
- **Drop**: Stash any local changes first (`git stash -u`), then use `mergify stack drop <SHA>...` to remove commits from the stack. Non-interactive — never use `git rebase -i` for this.
- **Commit titles**: Follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`)
- **PR title & body**: `mergify stack` copies the commit message title to the PR title and the commit message body to the PR body — so write commit messages as if they were PR descriptions. **Everything that should appear in the PR (ticket references, context, test plans) MUST go in the commit message.**
- **Ticket references**: Include ticket/issue references (e.g., `MRGFY-1234`, `Fixes #123`) in the commit message body, not added separately to the PR.
- **PR lifecycle is fully managed by `mergify stack`**: NEVER edit PR titles, bodies, or labels with `gh pr edit` or the GitHub MCP — they will be overwritten on the next push. NEVER close or merge PRs manually — `mergify stack` handles the entire PR lifecycle (creation, updates, and cleanup).
- **Draft PRs**: NEVER mark a PR as ready-for-review — all PRs stay as drafts. The user will manually move them out of draft after reviewing.
- **Each commi

Preview of the first 4,000 characters. Read full instructions →