mergify-config
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, Mergify merge queue config, pull_request_rules, queue_rules, Mergify conditions, conflict_resolvers, automatic merge conflict resolution.
How do I install this agent skill?
npx skills add https://github.com/mergifyio/mergify-cli --skill mergify-configIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill allows users to manage Mergify configurations by validating files, simulating actions, and fetching official documentation. It is generally secure but possesses a low-risk surface for indirect prompt injection, as it processes external documentation and local configuration files that could potentially contain instructions intended to influence the agent.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
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, in this order — the first one that exists wins:
.mergify.yml, then.mergify.yaml.mergify/config.yml, then.mergify/config.yaml.github/mergify.yml, then.github/mergify.yaml
Both extensions are read at every location, and .yml wins when a location
carries both. A repository holding more than one configuration file gets a
warning on stderr naming the file in use and the ones ignored — the engine
applies the same order, so the CLI reads whatever production reads.
Override with --config-file / -f:
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.
# 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:
- 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.
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 credentialmergify auth loginstored (your user runs it, see below). The CLI no longer falls back toGITHUB_TOKENorgh 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.
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-protections/setup |
| Custom protection rules | https://docs.mergify.com/merge-protections/custom-rules |
| Merge protection examples | https://docs.mergify.com/merge-protections/examples |
| Commands and restrictions | https://docs.mergify.com/commands |
| JSON Schema | https://docs.mergify.com/mergify-configuration-schema.json |
For individual actions (assign, backport, close, comment, copy, dismiss_reviews,
edit, github_actions, label, merge, queue, rebase, request_reviews, review,
squash, update), fetch the specific action page at
https://docs.mergify.com/workflow/actions/<action_name>.
Workflow
- Read the user's existing config (if any) to understand current state
- Fetch the relevant doc pages for the features the user needs
- Write or update the configuration based on the documentation
- Validate: run
mergify config validateto check for errors - Simulate (optional): run
mergify config simulate <PR_URL>against a real PR to verify the rules behave as expected
Resolving merge conflicts (conflict_resolvers)
Preview: it may still change, and is available on request.
The top-level conflict_resolvers key has Mergify resolve conflicts with the
base branch on the files its entries name, instead of leaving them to the pull
request's author. Start from the auto entry, which
leaves Mergify to pick a strategy file by file for every file it has one for
(a package manager's manifest and lockfile, source files by language,
Markdown, JSON, changelogs):
conflict_resolvers:
- auto: true
autonever picks a strategy that keeps one side's change only. A conflict its strategy declines (two pull requests changing the same key or the same dependency two ways) is still a conflict, and a file it has no strategy for merges as git would.directories(literal paths starting with/, default/) limits an entry to part of the repository.- The other entry kinds name files explicitly:
pathswith astrategy,package-managerwith itsdirectories, orlanguage. When several entries match a file the last one wins, except that any other entry beatsautowherever it sits, so an explicit entry is how to keep a file fromauto's strategy. ours,theirs,prefer-oursandprefer-theirsdiscard one side's change. Name one only when the user asks for that trade.- What it does depends on the queue rule's
merge_method:merge-batchandfast-forwardland the resolved batch; withmergeandsquash, once the entries settle every conflict, Mergify pushes the merge into the pull request while it is not queued;rebaseresolves nothing.
The conflict_resolvers description in the JSON schema
(https://docs.mergify.com/mergify-configuration-schema.json) lists every
strategy, language and package manager. Run mergify config validate after
editing.
Common Patterns
Test config changes before pushing
# Edit your .mergify.yml locally, then:
mergify config validate
mergify config simulate https://github.com/myorg/myrepo/pull/42
# If both look good, commit and push
CI validation gate
jobs:
validate-mergify:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Install mergify-cli
run: pip install mergify-cli
- name: Validate Mergify config
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 loginyourself. 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 loginat the prompt. Elsewhere, ask them to runmergify auth loginin 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/mergifyio/mergify-cli/mergify-config">View mergify-config on skillZs</a>