mergify-merge-protections

Mergify 合并保护

合并保护用于控制 PR 何时允许合并：

保护	范围	方式
Depends-On	单个 PR 的依赖链	PR 正文中的 Depends-On: 标头
Merge-After	单个 PR 的时间门槛	PR 正文中的 Merge-After: 标头
Scheduled Freezes	整个仓库或有条件地应用	CLI 命令（mergify freeze）

Depends-On 和 Merge-After 是内置功能——只需在 PR 描述中添加标头（使用 mergify stack push 时则添加到提交消息正文），Mergify 就会自动强制执行，无需配置 .mergify.yml。冻结通过 CLI 命令管理。

Depends-On

阻止 PR 合并，直到一个或多个其他 PR 先完成合并。

语法

在 PR 正文中添加一行或多行 Depends-On:：

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

支持以上三种格式——同一仓库使用 #NNN，跨仓库使用完整 URL 或 org/repo#NNN。

规则

• 所有引用的 PR 必须位于已启用 Mergify 的仓库中
• 所有引用的 PR 必须属于同一个 GitHub 组织
• 循环依赖和对自身的引用会被静默忽略
• 允许使用多行 Depends-On:（每行一条）

配合 mergify stack push 使用

stack 工具会自动在堆栈中连续的 PR 之间添加 Depends-On: #NNN。对于堆栈之外的依赖（跨仓库或无关 PR），请手动将标头添加到提交消息正文中——推送时它会被复制到 PR 描述中。

适用场景

• 跨多个仓库的功能（例如，API 变更和客户端更新）
• 应用程序代码合并前必须先合并架构迁移
• 消费方使用前必须先合并共享库更新

Merge-After

将合并推迟到指定的日期和时间。

语法

在 PR 正文中添加一行 Merge-After:：

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

支持的时间戳格式（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

如果未指定时区，则默认使用 UTC。

适用场景

• 协同发布：多个 PR 应在指定时间一并合并
• 在维护时段或非高峰时段合并
• 延迟公开：PR 已准备就绪，但不应在指定日期前发布

同时使用 Depends-On 和 Merge-After

同一个 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]

只有在 billing-service 中的 PR #42 已合并且指定时间已过后，该 PR 才会合并。

Scheduled Freezes

Scheduled freezes 会暂时停止合并符合特定条件的拉取请求。可将其用于部署窗口、事件响应、维护时段，或任何需要暂停合并的情况。

命令

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

身份验证

所有命令都需要 Mergify 凭证。运行一次 mergify auth login，或者使用：

• --token / -t（环境变量：MERGIFY_TOKEN）——Mergify 凭证。若未提供，则使用 mergify auth login 存储的凭证，再回退到 GITHUB_TOKEN / gh auth token；后两者已弃用，不再用于 Mergify API。
• --repository / -r——仓库全名（自动从 git remote 检测）
• --api-url / -u（环境变量：MERGIFY_API_URL）——Mergify API URL（默认值：https://api.mergify.com）

创建冻结

# 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"

必需选项：

• --reason——冻结原因，使用易读的描述
• --timezone——IANA 时区名称（例如，Europe/Paris、US/Eastern、UTC）

可选选项：

• --start——ISO 8601 格式的开始时间（默认值：现在）
• --end——ISO 8601 格式的结束时间（默认值：无结束时间，即紧急冻结）
• --condition / -c——匹配条件（可重复，例如，-c 'base=main'）
• --exclude / -e——排除条件（可重复，例如，-e 'label=hotfix'）

列出冻结

# Table view
mergify freeze list

# JSON output for scripting
mergify freeze list --json

该表显示：ID、原因、带时区的开始/结束时间、匹配条件，以及活动/已安排状态。

更新冻结

# 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"

FREEZE_ID 是 mergify freeze list 显示的 UUID。

删除冻结

# 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"

如果冻结当前处于活动状态，则必须提供用于删除的 --reason。

常见模式

事件期间的紧急冻结

# 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"

定期部署窗口

在每个部署窗口前创建冻结，并在窗口结束后删除：

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

冻结期间允许修复严重问题

mergify freeze create \
  --reason "Sprint freeze" \
  --timezone UTC \
  -c "base=main" \
  -e "label=hotfix" \
  -e "label=security"