Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ mergify ci junit-process report.xml # upload test results to Test Engine
laptop or a CI runner and go.
- **One command to sign in.** `mergify auth login` approves the CLI in your
browser and keeps the credential in your OS keychain; `MERGIFY_TOKEN` or
`--token` for scripting.
`--token` for scripting. In a GitHub Actions job granted `id-token: write`,
`mergify ci` needs neither: it exchanges the job's ID token.
- **Built for pipelines.** Logs to stderr, structured `--json` output on read
commands, and stable [exit codes](#exit-codes) for scripts and runbooks.
- **Cross-platform.** Linux (x86_64 + aarch64, glibc 2.28 or newer), macOS
Expand Down Expand Up @@ -95,12 +96,15 @@ Mergify API is dropping GitHub tokens, and a command with none of the credential
above fails and says how to get one. Run `mergify auth login`, or set
`MERGIFY_TOKEN` in CI.

`mergify ci` skips step 3. Those endpoints require an organization
application key, which is what `MERGIFY_TOKEN` holds in a CI job; the
per-user credential `mergify auth login` mints is refused there by design.
With an application key in `MERGIFY_TOKEN`, `mergify auth status` names the
key, its permissions and when it expires: a refused request never says which
permission it lacked.
`mergify ci` skips step 3: its endpoints take a CI credential, and refuse the
per-user one `mergify auth login` mints by design. In a GitHub Actions job
granted `id-token: write`, with neither `--token` nor `MERGIFY_TOKEN`,
`mergify ci junit-process` and `mergify ci scopes-send` exchange the job's ID
token for a short-lived Mergify token, once a trust policy of the organization
allows the job (`mergify oidc`, below). On any other CI, `MERGIFY_TOKEN` holds
an organization application key with the `ci` scope. With an application key
in `MERGIFY_TOKEN`, `mergify auth status` names the key, its permissions and
when it expires: a refused request never says which permission it lacked.

`mergify stack` also calls the **GitHub API** directly, and resolves that
token separately (`--token`, `MERGIFY_TOKEN`, `GITHUB_TOKEN`, `gh auth
Expand Down Expand Up @@ -220,7 +224,7 @@ These are accepted on every command:

| Variable | Effect |
| --- | --- |
| `MERGIFY_TOKEN` | API token. Takes precedence over a stored `mergify auth login` credential. |
| `MERGIFY_TOKEN` | API token. Takes precedence over a stored `mergify auth login` credential. Unset in a GitHub Actions job granted `id-token: write`, `mergify ci` exchanges the job's ID token instead. |
| `GITHUB_TOKEN` | Not a Mergify API credential. Still the GitHub token `mergify stack` uses. |
| `GITHUB_REPOSITORY` | Default `owner/repo` when `--repository` is omitted. |
| `MERGIFY_API_URL` | API base URL (default `https://api.mergify.com`). |
Expand Down
78 changes: 48 additions & 30 deletions skills/mergify-ci/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,11 @@ CLI calls, the two lists share only the quarantine list.
| `ci` | What a CI job does: trace upload, `scopes-send`, quarantine *evaluation* (`junit-process`) and the quarantine *list*. |
| `admin` | Reading test health, the quarantine *list*, and mutating the quarantine. Not trace upload, not `scopes-send`. |

Trace upload and `scopes-send` take a `ci` key only: an `admin` key or a
user credential gets a `403`. Every other endpoint below that refuses a `ci`
key accepts a user credential (`mergify auth login`) instead. `GITHUB_TOKEN`
Trace upload and `scopes-send` take only a `ci` key, or on GitHub Actions the
job's ID token ([below](#github-actions-jobs-need-no-key-oidc)): an `admin`
key or a user credential gets a `403`. Every other endpoint below that refuses a `ci`
key accepts a user credential (`mergify auth login`, which your user runs: see
[below](#when-a-command-says-there-is-no-mergify-credential)) instead. `GITHUB_TOKEN`
inside GitHub Actions is not a Mergify credential at all, so do not reach for
it to clear one of these `403`s.

Expand Down Expand Up @@ -72,8 +74,8 @@ trades its GitHub ID token for a short-lived token that does what a `ci` key
does, on its own repository only, when a trust policy of the organization
matches the job: `ci junit-process`, `ci scopes-send` and the test framework
plugins (2026.11.2 or later) do it themselves. A `MERGIFY_TOKEN` that is set
always wins. Writing a trust policy needs the Enterprise plan, and an
organization admin or CI Admin: see [OIDC Trust Policies](#oidc-trust-policies-mergify-oidc).
always wins. Writing a trust policy needs an organization admin or CI Admin:
see [OIDC Trust Policies](#oidc-trust-policies-mergify-oidc).
Fork pull requests get no ID token, as they get no secret. Jobs outside
GitHub Actions keep a `ci` key.

Expand All @@ -88,7 +90,7 @@ mergify ci junit-process \
path/to/junit-results.xml
```

The key is read from `MERGIFY_TOKEN`: set it in the job's environment from a secret rather than passing `--token`, which would put it in the process list.
On GitHub Actions, a job granted `id-token: write` needs no key (see [GitHub Actions jobs need no key](#github-actions-jobs-need-no-key-oidc)). On any other CI, the key is read from `MERGIFY_TOKEN`: set it in the job's environment from a secret rather than passing `--token`, which would put it in the process list.

`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.

Expand All @@ -110,21 +112,27 @@ The key is read from `MERGIFY_TOKEN`: set it in the job's environment from a sec
5. Exits with code 0 if all failures are quarantined, code 1 if any are blocking
6. If `--test-exit-code` is non-zero but no test failures are found, exits with code 1 (silent failure detection)
7. Upload failures never affect the exit code (Mergify-side trouble must not break CI), but they are surfaced: on GitHub Actions the command emits an `::error::` annotation when the upload is rejected (refused by the schema check, or HTTP 4xx except 408/429, e.g. a token without access to the repository, or Test Engine turned off for it: the annotation then gives Mergify's reason) or a `::warning::` annotation for transient errors (5xx, 408, 429, network), and appends `test_results_upload=success|rejected|failed` to `$GITHUB_OUTPUT` so workflows can detect dead ingest programmatically
8. With no `MERGIFY_TOKEN`, a job whose ID token Mergify refuses (no trust policy matches it yet) or does not exchange carries on without Mergify: nothing is uploaded and no test is quarantined, so it exits as points 5 and 6 say with every failure blocking. The report says `MERGIFY_TOKEN is not set, skipping the test results upload and the quarantine check.`, followed by Mergify's reason when it refused, and so does a `::warning::` annotation on GitHub Actions; `$GITHUB_OUTPUT` gets `test_results_upload=rejected`. A Mergify that cannot answer the exchange is an outage instead, reported as in point 7

**GitHub Actions example:**
```yaml
- name: Run tests
id: tests
run: pytest --junitxml=results.xml || echo "exit_code=$?" >> "$GITHUB_OUTPUT"

- name: Process test results
if: always()
run: |
mergify ci junit-process \
--test-exit-code ${{ steps.tests.outputs.exit_code || 0 }} \
results.xml
env:
MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
jobs:
test:
permissions:
id-token: write
contents: read
steps:
# ...
- name: Run tests
id: tests
run: pytest --junitxml=results.xml || echo "exit_code=$?" >> "$GITHUB_OUTPUT"

- name: Process test results
if: always() && (!github.event.pull_request || github.event.pull_request.head.repo.full_name == github.repository)
run: |
mergify ci junit-process \
--test-exit-code ${{ steps.tests.outputs.exit_code || 0 }} \
results.xml
```

## Git References (`git-refs`)
Expand Down Expand Up @@ -199,8 +207,8 @@ Sends scopes tied to a pull request to the Mergify API. Used when scopes are det

The report is addressed by the pull request's **head SHA**, so it says which revision it was computed for and a result computed for an older head cannot be taken for the current one. The head is detected from the CI environment (GitHub Actions event payload, `BUILDKITE_COMMIT`, `CIRCLE_SHA1`, or a Jenkins pull request build's checkout); pass `--head-sha` to name it explicitly wherever it is not detected: a GitHub Actions event with no `pull_request` payload (`push`, `workflow_run`, ...), any other CI. A Jenkins multibranch pull request build needs no flag: the number comes from `CHANGE_ID`, and the head is the commit checked out (`GIT_COMMIT`, else `HEAD`) or, when the GitHub Branch Source plugin merges the pull request into its target branch, the first parent of the merge Jenkins made. No head is detected where git cannot read the checkout, such as a container without its `.git`, nor on an agent that merges with JGit, whose merge Jenkins does not make under its own name: pass `--head-sha` with the pull request's head there, or switch the source's strategy to "The current pull request revision". When no head SHA can be resolved, the command reports against the pull request number alone and warns: that route is deprecated and will be removed. A Mergify deployment that predates the commit endpoint (on-premise before 8.18.0) gets the same pull request route without a warning.

Needs a `ci` key — an `admin` key or a user credential gets a `403`. See
[Authentication](#authentication).
Needs a `ci` key, or on GitHub Actions the job's ID token; an `admin` key or a
user credential gets a `403`. See [Authentication](#authentication).

```bash
# Send specific scopes
Expand Down Expand Up @@ -464,18 +472,16 @@ A GitHub Actions job gets a Mergify token for its ID token when one trust
policy of its organization matches it, and a policy matches when each of its
lines does: repositories, workflows, events and environments. Policies only
allow, with no order and no deny, so a narrow one cannot hold back a broad one.
OIDC is in Preview, open to every organization: it may still change.

Every `mergify oidc` command takes the organization with `--org`, else the
owner of the current repository, and the credential of one of its admins or CI
Admins (`mergify auth login`), or an application key with the OIDC trust
policies permission, and the repositories one to name repositories (an
`admin` key has both); a `ci` key gets a `403`. Creating or editing a policy
needs a plan that includes CI authentication with OIDC: without it Mergify
answers HTTP 402, and the jobs keep a `ci` key. Listing, deleting and the
exchanges never need it. Every command takes `--json`, which prints what
Mergify answered; `exchanges list --json` puts the exchanges under
`exchanges`, beside `since` and `truncated` (true when `--limit` left some
out).
`admin` key has both); a `ci` key gets a `403`. Every command takes `--json`,
which prints what Mergify answered; `exchanges list --json` puts the exchanges
under `exchanges`, beside `since` and `truncated` (true when `--limit` left
some out).

```bash
# Every policy, line by line.
Expand Down Expand Up @@ -559,15 +565,16 @@ This command is useful in CI workflows that need to know whether the current run
```yaml
jobs:
test:
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Run tests
run: pytest --junitxml=results.xml
- name: Upload and evaluate
if: always()
if: always() && (!github.event.pull_request || github.event.pull_request.head.repo.full_name == github.repository)
run: mergify ci junit-process results.xml
env:
MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
```

### Selective testing with scopes
Expand All @@ -590,6 +597,17 @@ jobs:
- run: pytest backend/
```

## When a command says there is no Mergify credential

On your user's machine, `no Mergify credential found` from `tests show`, `tests runs`, `tests quarantines` or `oidc` means neither `--token`, `MERGIFY_TOKEN` nor a stored login gave the CLI a credential. Stop and ask your user to log in:

- Don't run `mergify auth login` yourself. It prints a URL and a code, then waits until a person approves it in a browser: you cannot finish it, and the tool call hangs.
- In Claude Code, ask them to type `! mergify auth login` at the prompt. Elsewhere, ask them to run `mergify auth login` in their own terminal.
- Wait until they say it's done, then run the same command again.
- Don't read another source instead (CI logs, the GitHub API) without asking them first.

`ci junit-process` and `ci scopes-send` say something else when they find no credential: they need an application key in `MERGIFY_TOKEN` (or OIDC on GitHub Actions), which logging in does not provide.

## When a command or flag is missing

If `mergify` rejects a command or flag this skill names, the CLI is probably older than the skill: follow the `mergify-cli-upgrade` skill.
11 changes: 10 additions & 1 deletion skills/mergify-config/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ mergify config simulate https://github.com/owner/repo/pull/123
- `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. The CLI no longer falls back to `GITHUB_TOKEN` or `gh auth token`.
- `--token` / `-t` (env: `MERGIFY_TOKEN`) -- Mergify credential. Falls back to the credential `mergify auth login` stored (your user runs it, see [below](#when-a-command-says-there-is-no-mergify-credential)). The CLI no longer falls back to `GITHUB_TOKEN` or `gh auth token`.
- `--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.
Expand Down Expand Up @@ -185,6 +185,15 @@ jobs:
run: mergify config validate
```

## When a command says there is no Mergify credential

`no Mergify credential found` (from `simulate`, which asks the Mergify API) means neither `--token`, `MERGIFY_TOKEN` nor a stored login gave the CLI a credential. Stop and ask your user to log in:

- Don't run `mergify auth login` yourself. It prints a URL and a code, then waits until a person approves it in a browser: you cannot finish it, and the tool call hangs.
- In Claude Code, ask them to type `! mergify auth login` at the prompt. Elsewhere, ask them to run `mergify auth login` in their own terminal.
- Wait until they say it's done, then run the same command again.
- Don't guess what Mergify would do instead, or read another source, without asking them first.

## When a command or flag is missing

If `mergify` rejects a command or flag this skill names, the CLI is probably older than the skill: follow the `mergify-cli-upgrade` skill.
9 changes: 9 additions & 0 deletions skills/mergify-events/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,15 @@ The window is echoed so an empty `events` is self-describing. Filter with `jq` o
- **"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 pass `received_from` (the API silently defaults to 1 day) and keep the span ≤ 93 days.

## When a command says there is no Mergify credential

`no Mergify credential found` means neither `--token`, `MERGIFY_TOKEN` nor a stored login gave the CLI a credential. Stop and ask your user to log in:

- Don't run `mergify auth login` yourself. It prints a URL and a code, then waits until a person approves it in a browser: you cannot finish it, and the tool call hangs.
- In Claude Code, ask them to type `! mergify auth login` at the prompt. Elsewhere, ask them to run `mergify auth login` in their own terminal.
- Wait until they say it's done, then run the same command again.
- Don't look for the answer somewhere else (the GitHub API, the PR's comments) without asking them first.

## When a command or flag is missing

If `mergify` rejects a command or flag this skill names, the CLI is probably older than the skill: follow the `mergify-cli-upgrade` skill.
11 changes: 10 additions & 1 deletion skills/mergify-merge-protections/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ mergify freeze delete FREEZE_ID # Delete a freeze

## Authentication

All commands require a Mergify credential. Run `mergify auth login` once, or:
All commands require a Mergify credential: the one `mergify auth login` stores (your user runs it, see [below](#when-a-command-says-there-is-no-mergify-credential)), or:
- `--token` / `-t` (env: `MERGIFY_TOKEN`) -- Mergify credential. Falls back to the credential `mergify auth login` stored. The CLI no longer falls back to `GITHUB_TOKEN` or `gh auth token`.
- `--repository` / `-r` -- Repository full name (auto-detected from git remote)
- `--api-url` / `-u` (env: `MERGIFY_API_URL`) -- Mergify API URL (default: `https://api.mergify.com`)
Expand Down Expand Up @@ -224,6 +224,15 @@ mergify freeze create \
-e "label=security"
```

## When a command says there is no Mergify credential

`no Mergify credential found` means neither `--token`, `MERGIFY_TOKEN` nor a stored login gave the CLI a credential. Stop and ask your user to log in:

- Don't run `mergify auth login` yourself. It prints a URL and a code, then waits until a person approves it in a browser: you cannot finish it, and the tool call hangs.
- In Claude Code, ask them to type `! mergify auth login` at the prompt. Elsewhere, ask them to run `mergify auth login` in their own terminal.
- Wait until they say it's done, then run the same command again.
- Don't do it some other way, or read another source, without asking them first.

## When a command or flag is missing

If `mergify` rejects a command or flag this skill names, the CLI is probably older than the skill: follow the `mergify-cli-upgrade` skill.
9 changes: 9 additions & 0 deletions skills/mergify-merge-queue/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -420,6 +420,15 @@ mergify queue unpause
- Check for failing batches that trigger bisection: `mergify queue status`
- Bisecting batches test PRs individually, which is slower than batch merging

## When a command says there is no Mergify credential

`no Mergify credential found` means neither `--token`, `MERGIFY_TOKEN` nor a stored login gave the CLI a credential. Stop and ask your user to log in:

- Don't run `mergify auth login` yourself. It prints a URL and a code, then waits until a person approves it in a browser: you cannot finish it, and the tool call hangs.
- In Claude Code, ask them to type `! mergify auth login` at the prompt. Elsewhere, ask them to run `mergify auth login` in their own terminal.
- Wait until they say it's done, then run the same command again.
- Don't look for the answer somewhere else (the GitHub API, the PR's comments) without asking them first.

## When a command or flag is missing

If `mergify` rejects a command or flag this skill names, the CLI is probably older than the skill: follow the `mergify-cli-upgrade` skill.
Loading