mergify-ci

Mergify CI コマンド

概要

mergify ci コマンドグループは、CI パイプライン向けのツールを提供します。JUnit テスト結果を Mergify CI Insights にアップロードする、diff ベースの操作のために git 参照を検出する、選択的テストのために CI スコープを管理する、マージキューのバッチメタデータを取得する、といったことができます。

コマンド

mergify ci junit-process FILES...         # Upload JUnit XML + evaluate quarantine (primary command)
mergify ci junit-upload FILES...          # (Deprecated) Use junit-process instead
mergify ci git-refs                       # Detect base/head git references for the current PR
mergify ci scopes --config PATH           # Detect scopes impacted by changed files
mergify ci scopes-send -s SCOPE           # Report scopes against the pull request's head commit
mergify ci queue-info                     # Output the current build's merge queue batch metadata (from the git note)
mergify tests show NAME...                # Look up tests by name and print health, ratios, last failure
mergify tests quarantines add NAME        # Add a test to the CI Insights quarantine
mergify tests quarantines remove NAME     # Remove a test from the CI Insights quarantine
mergify tests quarantines get NAME        # Print a single quarantine by test name or id
mergify tests quarantines list            # List the tests currently in the CI Insights quarantine

認証

Mergify アプリケーションキーには 2 つのクラスがあり、どちらもダッシュボードで発行されます。それぞれが到達できるエンドポイントの一覧は独自のものであり、一方が他方のサブセットというわけではありません。この CLI が呼び出すもののうち、2 つの一覧で共通するのは隔離リストだけです。

キー	到達できる範囲
ci	CI ジョブが行うこと: トレースのアップロード、scopes-send、隔離の評価(junit-process)と隔離のリスト。
admin	テストヘルスの読み取り、隔離のリスト、および隔離の変更。トレースのアップロードは不可、scopes-send も不可。

トレースのアップロードと scopes-send は ci キーのみを受け付けます。admin キーや GitHub PAT では 403 になります。以下で ci キーを拒否するその他のエンドポイントはすべて、代わりに GitHub の PAT を受け付けます。GitHub Actions 内の GITHUB_TOKEN は PAT ではありません — これは一時的なインストールトークンです — そのため、これらの 403 を解消するためにこれを使おうとしないでください。

この区分は各コマンドが呼び出すエンドポイントに従っています。テストヘルスの読み取りと隔離への書き込みは、パイプラインが行うことではなく、人が検査または上書きする操作であるため、ci キーが持つ範囲外です。トレースのアップロードとスコープレポートはパイプラインが送信するものであるため、admin キーが持つ範囲外です。コマンドごとには次のとおりです。

コマンド	ci キー	admin キー
ci junit-process, ci junit-upload	可	隔離の評価のみ — アップロードは 403 となり、拒否されたアップロードとして報告されます(終了コードには影響しません)
ci scopes-send	可	不可 — 403
tests quarantines list, tests quarantines remove	可 — どちらも隔離リストを読み取ります	可
tests show	不可 — 403	可
tests quarantines add, tests quarantines remove	不可 — 403	可

ci git-refs、ci scopes、ci queue-info はローカルで評価されるため、トークンはまったく必要ありません。

JUnit 処理 (junit-process)

主要な CI コマンドです。JUnit XML レポートを解析し、失敗したテストの隔離ステータスを確認し、結果を Mergify CI Insights にアップロードし、最終的な CI 終了コードを決定します。

mergify ci junit-process \
  --token "$MERGIFY_TOKEN" \
  --repository owner/repo \
  --tests-target-branch main \
  path/to/junit-results.xml

FILES には個別のパスまたは引用符で囲んだ glob パターン（例: 'reports/**/*.xml'）を指定できます。パターンは必ず引用符で囲んでください。これによりシェルではなく Mergify がパターンを展開します。これは大規模でシャーディングされたテストスイートに推奨される方法です。

主なオプション:

• --token / -t (env: MERGIFY_TOKEN) -- CI Insights のアプリケーションキー
• --repository / -r -- リポジトリの完全名（CI プロバイダー、次に git リモートから自動検出されます）
• --tests-target-branch / -ttb -- 隔離の評価に使用されるブランチ。CI プロバイダーごとに自動検出されます: GitHub Actions (GITHUB_BASE_REF → GITHUB_HEAD_REF → GITHUB_REF_NAME)、Buildkite (BUILDKITE_PULL_REQUEST_BASE_BRANCH → BUILDKITE_BRANCH)、CircleCI (CIRCLE_BRANCH)、Jenkins (CHANGE_TARGET → GIT_BRANCH)、そしてチェックアウトされたブランチ。
• --api-url / -u (env: MERGIFY_API_URL) -- Mergify API の URL（デフォルト: https://api.mergify.com）
• --test-framework -- テストフレームワーク名（任意のメタデータ）
• --test-language -- テスト言語（任意のメタデータ）
• --test-exit-code / -e (env: MERGIFY_TEST_EXIT_CODE) -- テストランナーの終了コード。ランナーがクラッシュしたのに JUnit レポートは正常に見えるサイレント障害を検出するために使用されます
• MERGIFY_TRACEPARENT (env のみ) -- アップロードされたテストセッションを、呼び出し元がすでに開始したトレース内に配置するための W3C traceparent。不正な形式の値は無視され、セッションは独自のトレースを開始します

動作:

1. JUnit XML ファイルをテストスパンに解析します
2. Mergify API に対して失敗したテストの隔離ステータスを確認します
3. すべてのテストスパンを Mergify CI Insights にアップロードします
4. サマリーを出力します: 実行されたテスト、失敗、隔離済みかブロッキングか
5. すべての失敗が隔離済みであればコード 0 で終了し、ブロッキングとなる失敗があればコード 1 で終了します
6. --test-exit-code が非ゼロであるにもかかわらず、テスト失敗が検出されなかった場合は、コード 1 で終了します（サイレント障害の検出）
7. アップロードの失敗が終了コードに影響を与えることはありません（Mergify 側のトラブルで CI を壊してはならないため）が、表面化はされます: GitHub Actions では、アップロードが拒否された場合（HTTP 4xx、ただし 408/429 を除く。例: CI Insights へのアクセス権がないトークン）にコマンドが ::error:: アノテーションを、一時的なエラー（5xx、408、429、ネットワーク）に対しては ::warning:: アノテーションを出力し、test_results_upload=success|rejected|failed を $GITHUB_OUTPUT に追記するため、ワークフローは取り込みの停止をプログラムで検出できます

GitHub Actions の例:

- name: Run tests
  id: tests
  run: pytest --junitxml=results.xml || echo "exit_code=$?" >> "$GITHUB_OUTPUT"

- name: Process test results
  if: always()
  run: |
    mergify ci junit-process \
      --test-exit-code ${{ steps.tests.outputs.exit_code || 0 }} \
      results.xml
  env:
    MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}

Git 参照 (git-refs)

現在のプルリクエストのコンテキストにおけるベースとヘッドの git 参照を検出します。GitHub Actions で実行されている場合は結果を GITHUB_OUTPUT に、Buildkite で実行されている場合は Buildkite のメタデータ（mergify-ci.base、mergify-ci.head、mergify-ci.source）に書き込みます。

mergify ci git-refs
# Output:
# Base: abc1234
# Head: def5678

出力形式 (--format):

• text（デフォルト） — 人間が読める Base: / Head: の行
• shell — eval に適した MERGIFY_GIT_REFS_{BASE,HEAD,SOURCE}=... の行。POSIX セーフなシェルクォート付き。base を検出できない場合は MERGIFY_GIT_REFS_BASE=''。
• json — base、head、source キーを持つ単一行の JSON オブジェクト。base は検出できない場合（例: workflow_dispatch イベント）に null になることがあります。空文字列に変換するには jq -r '.base // ""' を使用してください。

# Consume values in a shell script without parsing:
eval "$(mergify ci git-refs --format=shell)"
nx show projects --affected \
  --base="$MERGIFY_GIT_REFS_BASE" \
  --head="$MERGIFY_GIT_REFS_HEAD"

# Or with jq:
BASE=$(mergify ci git-refs --format=json | jq -r '.base // ""')

検出されるソース（優先順）: マージキューのコンテキスト、GitHub プルリクエストイベント、GitHub プッシュイベント、最後のコミットへのフォールバック。

スコープ (scopes)

Mergify 設定ファイルに基づいて、変更されたファイルによって影響を受ける CI スコープを検出します。選択的・対象を絞った CI で使用します -- 変更されたファイルがあるスコープのテストのみを実行します。

# Detect scopes from changed files
mergify ci scopes --config .mergify.yml

# Detect scopes with explicit base/head
mergify ci scopes --config .mergify.yml --base origin/main --head HEAD

# Write detected scopes to a file
mergify ci scopes --config .mergify.yml --write scopes.json

主なオプション:

• --config (env: MERGIFY_CONFIG_PATH) -- Mergify YAML 設定ファイルへのパス (自動検出)
• --base -- ベースとなる git 参照 (自動検出)
• --head -- ヘッドとなる git 参照 (デフォルト: HEAD)
• --write / -w -- 検出したスコープを JSON ファイルに書き込む

設定ファイルはファイルパターンとともにスコープを定義します。ベースとヘッドの間でファイルが変更されると、一致するスコープが特定され、GITHUB_OUTPUT (GitHub Actions の場合) または mergify-ci.scopes 配下の Buildkite メタデータ (Buildkite の場合) に、スコープ名から "true"/"false" への JSON マップとして書き込まれます。

マージキューのドラフトプルリクエストでは、スコープは変更されたファイルから計算されません。このコマンドはバッチに関するエンジンの git note を読み取り、マージキューが決定したスコープ (バッチのスコープに加えて、各バッチ対象プルリクエストのスコープ。プルリクエストの CI が報告したスコープを含む) と、マージキュー自体のスコープを返します。note がバリア (all_scopes: true) としてマークしているバッチは、すべてのスコープを選択します。これは manual スコープソースでも機能します。note がない場合、または scopes リストのない note の場合は、ファイルの差分比較にフォールバックします。

リネームされたファイルは、エンジンと同様に、両方のパスに対してカウントされます。git mv critical/guard.txt ignored/guard.txt は critical と ignored の両方に影響します。

スコープ送信 (scopes-send)

プルリクエストに紐づくスコープを Mergify API に送信します。スコープが自動検出ではなく、手動またはファイルから決定される場合に使用します。

レポートはプルリクエストのヘッド SHA を宛先とするため、どのリビジョンに対して計算されたかが示され、古いヘッドに対して計算された結果を現在のものと見なすことはできません。ヘッドは CI 環境から検出されます (GitHub Actions のイベントペイロード、または BUILDKITE_COMMIT)。明示的に指定するには --head-sha を渡します。ヘッド SHA を解決できない場合 -- または Mergify のデプロイがコミットエンドポイントより前のものである場合 -- このコマンドはこれまでどおり、プルリクエスト番号のみに対してレポートするようフォールバックします。

ci キーが必要です -- admin キーまたは GitHub PAT では 403 になります。詳しくは 認証を参照してください。

# Send specific scopes
mergify ci scopes-send -s frontend -s backend -p 123

# Send scopes from a JSON file (produced by `mergify ci scopes --write`)
mergify ci scopes-send --scopes-json scopes.json -p 123

# Send scopes from a plain-text file (one scope per line)
mergify ci scopes-send --scopes-file scopes.txt -p 123

# Declare the PR impacts every scope (merge-queue barrier),
# e.g. a build-system or CI-workflow change
mergify ci scopes-send -s build-system --all -p 123

# Name the revision explicitly (the pull request head, not the
# revision a `pull_request` job checked out)
mergify ci scopes-send -s frontend -p 123 --head-sha "$PR_HEAD_SHA"

主なオプション:

• --token / -t (env: MERGIFY_TOKEN) -- Mergify の ci アプリケーションキー
• --repository / -r -- リポジトリのフルネーム (自動検出)
• --pull-request / -p -- プルリクエスト番号 (GitHub Actions では自動検出)
• --scope / -s -- スコープ名 (繰り返し指定可能)
• --scopes-json -- スコープを含む JSON ファイル (mergify ci scopes --write の出力)
• --scopes-file -- 1 行につき 1 つのスコープを記述したプレーンテキストファイル
• --head-sha -- スコープの計算対象となったヘッド SHA、40 桁の 16 進数文字 (CI 環境から自動検出)
• --all -- プルリクエストがすべてのスコープに影響することを宣言します。マージキューはこれをバリアとして扱い、他のプルリクエストとバッチ化されたり並行して実行されたりすることはありません。具体的なスコープはこのフラグとともに引き続き送信されます。

テスト表示 (tests show)

リポジトリのデフォルトブランチ上のテストを名前で検索し、その健全性、成功/失敗比率、最後の失敗コンテキストを出力します。検索はバッチ API です。1 つ以上の名前 (glob 対応) を渡すと、一致ごとに 1 ブロックが描画されます。これは読み取り専用です。一致を描画した時点で 0 で終了します。健全性がどうであれ変わりません。健全性でゲートするには、終了コードではなく --json を消費してください。

admin キーまたは GitHub PAT が必要です。ci キーでは 403 になります。認証 を参照してください。

# Single test.
mergify tests show -r owner/repo \
  'ApplicationKeys.spec.ts.Permissions › Should not see keys table if not admin'

# Batch with glob, narrowed to one pipeline, JSON for jq.
mergify tests show -r owner/repo \
  --pipeline-name e2e --json \
  '*test_login*' '*test_logout*' \
  | jq '.tests[] | {test_name, health_status}'

主なオプション:

• --repository / -r -- リポジトリのフルネーム (owner/repo)。省略時は CI 環境またはローカルの git リモートから自動検出されます。
• --token / -t (env: MERGIFY_TOKEN) -- Mergify の認証情報。mergify auth login が保存した認証情報にフォールバックし、次に GITHUB_TOKEN / gh auth token にフォールバックしますが、どちらも Mergify API では非推奨です。
• --api-url / -u (env: MERGIFY_API_URL) -- API ベース URL。
• --pipeline-name, --pipeline-name-exclude -- パイプラインで制限 / 除外します。
• --job-name, --job-name-exclude -- ジョブで制限 / 除外します。
• --per-page -- 検索結果の件数を上限設定します (1〜100、サーバーデフォルトは 10)。
• --json -- 単一の JSON ドキュメント {"tests": [...]} を stdout に出力します。

終了コード:

• 0 -- テストが描画された、または一致がまったくなかった。健全性は影響しません。
• 6 -- Mergify API エラー。ここで ci キーが受け取る 403 を含みます。

テスト隔離追加 (tests quarantines add)

リポジトリの CI Insights 隔離にテストを追加し、その失敗が CI の判定をブロックしなくなるようにします。完全修飾された単一のテスト名を取ります。--reason は必須です。

admin キーまたは GitHub PAT が必要です。ci キーでは 403 になります。認証 を参照してください。

# Quarantine on all branches.
mergify tests quarantines add -r owner/repo \
  --reason 'flaky — tracked in MRGFY-1234' \
  'test_login'

# Scope the quarantine to one branch (or branch pattern), JSON output.
mergify tests quarantines add -r owner/repo \
  --reason 'broken on release branch' --branch 'release/*' --json \
  'test_logout'

主なオプション:

• --repository / -r -- リポジトリのフルネーム (owner/repo)。省略時は CI 環境またはローカルの git リモートから自動検出されます。
• --reason -- 隔離のために記録される理由。必須です。
• --branch / -b -- 対象を絞るブランチ名またはパターン。すべてのブランチを対象にする場合は省略します。
• --token / -t (env: MERGIFY_TOKEN) -- Mergify の認証情報。mergify auth login が保存した認証情報にフォールバックし、次に GITHUB_TOKEN / gh auth token にフォールバックしますが、どちらも Mergify API では非推奨です。
• --api-url / -u (env: MERGIFY_API_URL) -- API ベース URL。
• --json -- {"id", "test_name", "reason", "branch"} を stdout に出力します。

終了コード:

• 0 -- テストが隔離されました。
• 6 -- Mergify API エラー (例: テストがすでに隔離されている)。

テスト隔離解除 (tests quarantines remove)

隔離からテストを削除します。完全修飾されたテスト名 (リストエンドポイントを介してその隔離 id に解決される) または隔離 id を直接 (tests quarantines add が出力したもの) のいずれかを受け付けます。UUID 形式の引数は id として扱われ、検索なしで削除されます。

admin キーまたは GitHub PAT が必要です。ci キーでは 403 になります。認証 を参照してください。

# By test name.
mergify tests quarantines remove -r owner/repo 'test_login'

# By quarantine id (the value `tests quarantines add` printed).
mergify tests quarantines remove -r owner/repo 12345678-1234-5678-1234-567812345678

主なオプション:

• --repository / -r -- リポジトリのフルネーム (owner/repo)。省略時は CI 環境またはローカルの git リモートから自動検出されます。
• --token / -t (env: MERGIFY_TOKEN) -- Mergify の認証情報。mergify auth login が保存した認証情報にフォールバックし、次に GITHUB_TOKEN / gh auth token にフォールバックしますが、どちらも Mergify API では非推奨です。
• --api-url / -u (env: MERGIFY_API_URL) -- API ベース URL。
• --json -- {"id", "test_name"} を stdout に出力します (id で指定した場合、test_name は null です)。

終了コード:

• 0 -- テストの隔離が解除されました。
• 6 -- Mergify API エラー (例: テストが隔離されていない)。

テストの隔離取得 (tests quarantines get)

完全修飾されたテスト名または隔離 ID で指定した単一の隔離を出力します（UUID 形式の引数は ID と照合されます）。出力は tests quarantines list の 1 レコードを反映したものになります。

# By test name.
mergify tests quarantines get -r owner/repo 'test_login'

# By quarantine id, JSON output.
mergify tests quarantines get -r owner/repo --json \
  12345678-1234-5678-1234-567812345678

主なオプション:

• --repository / -r -- リポジトリの完全名 (owner/repo)。省略時は CI 環境またはローカルの git リモートから自動検出されます。
• --token / -t (env: MERGIFY_TOKEN) -- Mergify の認証情報。mergify auth login が保存した認証情報にフォールバックし、次に GITHUB_TOKEN / gh auth token にフォールバックしますが、これらは Mergify API では非推奨です。
• --api-url / -u (env: MERGIFY_API_URL) -- API のベース URL。
• --json -- レコード (id、test_name、reason、branch、created_at、source、is_recovered) を stdout に出力します。

終了コード:

• 0 -- 隔離が見つかり、出力されました。
• 6 -- Mergify API エラー (例: 一致する隔離がない)。

テストの隔離一覧 (tests quarantines list)

現在リポジトリの CI Insights 隔離にあるすべてのテストを一覧表示します。テスト引数は取らず、隔離全体を出力します。人間が読む形式の出力は 1 レコードにつき 1 つのインデントされたブロックで、テスト名が単独の行 (名前の途中で折り返されません)、次にその id (delete が受け付ける値)、ブランチ、ソース、復旧済みかどうか、理由が続きます。--json は完全なレコードを出力します。

# Human output (one block per record).
mergify tests quarantines list -r owner/repo

# JSON for jq -- e.g. names of quarantines an auto-recover run flagged.
mergify tests quarantines list -r owner/repo --json \
  | jq -r '.quarantined_tests[] | select(.is_recovered) | .test_name'

branch が null の場合は * として表示されます (その隔離はすべてのブランチに適用されます)。 source は manual (ユーザーによって追加) または auto (フレーキー検出によって追加) です。 is_recovered は、最近の実行から削除可能と考えられる隔離を示すフラグです。

主なオプション:

• --repository / -r -- リポジトリの完全名 (owner/repo)。省略時は CI 環境またはローカルの git リモートから自動検出されます。
• --token / -t (env: MERGIFY_TOKEN) -- Mergify の認証情報。mergify auth login が保存した認証情報にフォールバックし、次に GITHUB_TOKEN / gh auth token にフォールバックしますが、これらは Mergify API では非推奨です。
• --api-url / -u (env: MERGIFY_API_URL) -- API のベース URL。
• --json -- {"quarantined_tests": [...]} を stdout に出力し、各レコードに id、test_name、reason、branch、created_at、source、is_recovered を含めます。

終了コード:

• 0 -- 常に (隔離が空の場合も含む。「No quarantined tests found.」)。

キューの情報 (queue-info)

現在のビルドのマージキューバッチメタデータを JSON として出力します。Mergify が現在の HEAD に対してマージキューブランチの先頭に書き込む git ノート refs/notes/mergify/<branch> を読み取ります。ノートが見つからない場合 (つまりマージキューバッチのビルドではない場合) は INVALID_STATE (7) で終了します。引数は取らず、GitHub トークンも必要ありません。

ノートの完全なペイロードはそのまま (Mergify が書き込んだすべてのフィールド、例: checking_base_sha、PR ごとの scopes を含む pull_requests、previous_failed_batches、トップレベルの scopes) 出力されます。新しいフィールドは CLI の更新なしで自動的に現れるため、固定のスキーマを前提にしないでください。

# In CI, on a merge queue batch build. Works in any CI (GitHub Actions,
# GitLab, CircleCI, Jenkins, ...) with plain git. When GITHUB_OUTPUT is
# set (GitHub Actions runner) it also writes the metadata there.
mergify ci queue-info

Mergify はバッチメタデータを MQ ブランチの先頭コミットに対する git ノートとして添付するため、その読み取りには git だけが必要で、PR 本文も GitHub トークンも不要です。このコマンドは自身で git fetch origin "refs/notes/mergify/*" を実行し (ノートはデフォルトでは取得されません)、その後 HEAD に添付されたノートを返します。要件: origin リモートに到達可能であり、チェックアウトが MQ ブランチの先頭コミットにあること。これはマージキュー CI 実行内での通常の状態です。デタッチド HEAD でも問題ありません。

このコマンドは、現在の実行がマージキューバッチの一部であるかどうか、およびバッチにどの他の PR が含まれているかを知る必要がある CI ワークフローで役立ちます。

一般的なパターン

隔離を含む完全な CI パイプライン

jobs:
  test:
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: pytest --junitxml=results.xml
      - name: Upload and evaluate
        if: always()
        run: mergify ci junit-process results.xml
        env:
          MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}

スコープを使用した選択的テスト

jobs:
  detect:
    outputs:
      scopes: ${{ steps.scopes.outputs.scopes }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - id: scopes
        run: mergify ci scopes --config .mergify.yml

  backend:
    needs: detect
    if: fromJSON(needs.detect.outputs.scopes).backend == 'true'
    steps:
      - run: pytest backend/