mergify-merge-protections

Mergify マージ保護

マージ保護は、PR をいつマージできるかを制御します。

保護	スコープ	方法
Depends-On	PR ごとの依存関係チェーン	PR 本文の Depends-On: ヘッダー
Merge-After	PR ごとの時間ゲート	PR 本文の Merge-After: ヘッダー
スケジュールされたフリーズ	リポジトリ全体または条件付き	CLI コマンド (mergify freeze)

Depends-On と Merge-After は組み込みです — PR の説明 (または mergify stack push を使用する場合はコミットメッセージ本文) にヘッダーを追加するだけで、Mergify が自動的に適用します。.mergify.yml の設定は不要です。フリーズは CLI コマンドで管理します。

Depends-On

他の 1 つ以上の PR が先にマージされるまで、PR のマージをブロックします。

構文

PR 本文に 1 行以上の Depends-On: 行を追加します。

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

3 つの形式すべてがサポートされています — 同一リポジトリには #NNN を、クロスリポジトリには完全な URL または org/repo#NNN を使用します。

ルール

• 参照されるすべての PR は、Mergify が有効になっているリポジトリにある必要があります
• 参照されるすべての PR は、同じ GitHub 組織に属している必要があります
• 循環依存と自己参照は黙って無視されます
• 複数の Depends-On: 行が許可されています (1 行に 1 つ)

mergify stack push との併用

スタックツールは、スタック内の連続する PR 間に Depends-On: #NNN を自動的に追加します。スタック外の依存関係 (クロスリポジトリまたは無関係な PR) については、コミットメッセージ本文に手動でヘッダーを追加してください — push 時に 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]

この PR は、billing-service の PR #42 がマージされ、かつ指定された時刻が過ぎるまでマージされません。

スケジュールされたフリーズ

スケジュールされたフリーズは、特定の条件に一致するプルリクエストのマージを一時的に停止します。デプロイウィンドウ、インシデント対応、メンテナンス期間、またはマージを一時停止すべきあらゆる状況で使用してください。

コマンド

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 (env: MERGIFY_TOKEN) -- Mergify の認証情報。mergify auth login が保存した認証情報にフォールバックし、次に GITHUB_TOKEN / gh auth token にフォールバックしますが、どちらも Mergify API では非推奨です。
• --repository / -r -- リポジトリの完全名 (git remote から自動検出)
• --api-url / -u (env: 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"