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

mergify-merge-protections

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 Mergify scheduled freezes, or when blocking a PR on another PR or delaying its merge with Mergify's Depends-On or Merge-After headers. Triggers on mergify freeze, Mergify scheduled freeze, Mergify merge freeze, Depends-On, Merge-After, Mergify merge protection.

How do I install this agent skill?

npx skills add https://github.com/mergifyio/mergify-cli --skill mergify-merge-protections
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides instructions for managing Mergify merge protections, such as PR dependencies and scheduled freezes. It uses standard Mergify CLI commands and PR headers and includes proper guidance on credential management and user interaction.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Mergify Merge Protections

Merge protections control when PRs are allowed to merge:

ProtectionScopeHow
Depends-OnPer-PR dependency chainDepends-On: header in PR body
Merge-AfterPer-PR time gateMerge-After: header in PR body
Scheduled FreezesRepository-wide or conditionalCLI 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

mergify freeze list                       # List all scheduled freezes
mergify freeze list --json                # Machine-readable JSON output
mergify freeze create OPTIONS             # Create a new scheduled freeze
mergify freeze update FREEZE_ID OPTIONS   # Update an existing freeze
mergify freeze delete FREEZE_ID           # Delete a freeze

Authentication

All commands require a Mergify credential: the one mergify auth login stores (your user runs it, see below), 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)

Creating a Freeze

# Emergency freeze (starts now, no end time)
mergify freeze create \
  --reason "Production incident - halting all merges" \
  --timezone "US/Eastern"

# Scheduled maintenance window
mergify freeze create \
  --reason "Weekend deployment freeze" \
  --timezone "Europe/Paris" \
  --start "2024-12-20T18:00:00" \
  --end "2024-12-23T08:00:00"

# Freeze with conditions (only freeze merges to main)
mergify freeze create \
  --reason "Release freeze for v2.0" \
  --timezone "UTC" \
  -c "base=main"

# Freeze with exclusions (allow hotfix PRs through)
mergify freeze create \
  --reason "Code freeze" \
  --timezone "UTC" \
  -c "base=main" \
  -e "label=hotfix"

Required options:

  • --reason -- Human-readable reason for the freeze
  • --timezone -- IANA timezone name (e.g., Europe/Paris, US/Eastern, UTC)

Optional options:

  • --start -- Start time in ISO 8601 format (default: now)
  • --end -- End time in ISO 8601 format (default: no end, emergency freeze)
  • --condition / -c -- Matching condition (repeatable, e.g., -c 'base=main')
  • --exclude / -e -- Exclude condition (repeatable, e.g., -e 'label=hotfix')

Listing Freezes

# Table view
mergify freeze list

# JSON output for scripting
mergify freeze list --json

The table shows: ID, reason, start/end times with timezone, matching conditions, and active/scheduled status.

Updating a Freeze

# Extend a freeze
mergify freeze update FREEZE_ID --end "2024-12-24T08:00:00"

# Change the reason
mergify freeze update FREEZE_ID --reason "Extended: waiting for hotfix"

# Set exclusions (replaces the full exclusion list, does not append)
mergify freeze update FREEZE_ID -e "label=emergency"

The FREEZE_ID is the UUID shown in mergify freeze list.

Deleting a Freeze

# Delete a scheduled (not yet active) freeze
mergify freeze delete FREEZE_ID

# Delete an active freeze (reason required)
mergify freeze delete FREEZE_ID --reason "Incident resolved"

If the freeze is currently active, a --reason for deletion is required.

Common Patterns

Emergency freeze during an incident

# Stop all merges immediately
mergify freeze create \
  --reason "Incident #1234 - API outage" \
  --timezone UTC

# Once resolved, delete the freeze
mergify freeze list --json  # Get the freeze ID
mergify freeze delete FREEZE_UUID --reason "Incident #1234 resolved"

Recurring deployment window

Create the freeze before each deployment window and delete it after:

mergify freeze create \
  --reason "Deploy window" \
  --timezone "US/Pacific" \
  --start "2024-12-20T14:00:00" \
  --end "2024-12-20T16:00:00"

Freeze with exceptions for critical fixes

mergify freeze create \
  --reason "Sprint freeze" \
  --timezone UTC \
  -c "base=main" \
  -e "label=hotfix" \
  -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.

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-merge-protections">View mergify-merge-protections on skillZs</a>