skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
mergifyio/mergify-cli81 installs

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-config
view source ↗

Is 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 credential mergify auth login stored (your user runs it, see below). 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.

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:

TopicURL
File format and structurehttps://docs.mergify.com/configuration/file-format
Conditions syntax and attributeshttps://docs.mergify.com/configuration/conditions
Data types (duration, templates)https://docs.mergify.com/configuration/data-types
Configuration sharing and reusehttps://docs.mergify.com/configuration/sharing
Workflow automation overviewhttps://docs.mergify.com/workflow
All available actionshttps://docs.mergify.com/workflow/actions
Writing your first rulehttps://docs.mergify.com/workflow/writing-your-first-rule
Merge queue ruleshttps://docs.mergify.com/merge-queue/rules
Merge queue setuphttps://docs.mergify.com/merge-queue/setup
Queue priority ruleshttps://docs.mergify.com/merge-queue/priority
Merge protectionshttps://docs.mergify.com/merge-protections/setup
Custom protection ruleshttps://docs.mergify.com/merge-protections/custom-rules
Merge protection exampleshttps://docs.mergify.com/merge-protections/examples
Commands and restrictionshttps://docs.mergify.com/commands
JSON Schemahttps://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

  1. Read the user's existing config (if any) to understand current state
  2. Fetch the relevant doc pages for the features the user needs
  3. Write or update the configuration based on the documentation
  4. Validate: run mergify config validate to check for errors
  5. 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
  • auto never 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: paths with a strategy, package-manager with its directories, or language. When several entries match a file the last one wins, except that any other entry beats auto wherever it sits, so an explicit entry is how to keep a file from auto's strategy.
  • ours, theirs, prefer-ours and prefer-theirs discard 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-batch and fast-forward land the resolved batch; with merge and squash, once the entries settle every conflict, Mergify pushes the merge into the pull request while it is not queued; rebase resolves 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 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.

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>