ステータスチェックで保護されたブランチをプルリクエストではなく GitHub API を使ってマージした際の挙動を確認してみた

#GitHub
若槻龍太
2024.08.16
こんにちは、製造ビジネステクノロジー部の若槻です。
GitHub で開発を行う際には、通常は head ブランチのプルリクエストを作成し base ブランチへマージする開発フローとなりますが、場合によってはコードの更新を自動化するためにプルリクエストを使いたくないケースがあります。
しかし base ブランチはルールセットで保護されている場合がほとんどであるため、今回はステータスチェックで保護されたブランチをプルリクエストではなく GitHub API を使ってマージした際の挙動を確認してみました。
 やってみたブランチのマージで使用した GitHub API はこちらです。この API を使うことにより、プルリクエストを作成せずに base ブランチへマージすることができます。
https://docs.github.com/en/rest/branches/branches?apiVersion=2022-11-28#merge-a-branch
マージする head ブランチは、ステータスチェックが成功、失敗および未実施の 3 パターンで試してみます。

リポジトリに適用されているルールセットは以下のようにしています。実際に使用されるルールとは乖離していると思いますが、検証の単純化のためにステータスチェック（Integration）のみを必須としています。
{
  "id": 1419308,
  "name": "デフォルトブランチ保護",
  "target": "branch",
  "source_type": "Repository",
  "source": "cm-rwakatsuki/test-public",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": ["~DEFAULT_BRANCH"]
    }
  },
  "rules": [
    {
      "type": "non_fast_forward"
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": true,
        "do_not_enforce_on_create": false,
        "required_status_checks": [
          {
            "context": "Integration",
            "integration_id": 15368
          }
        ]
      }
    }
  ],
  "bypass_actors": []
}
 ステータスチェックが失敗したブランチの場合ステータスチェックが失敗しているブランチ cm-rwakatsuki-patch-1 で試してみます。
$ curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/repos/cm-rwakatsuki/test-public/merges \
  -d '{"base":"main","head":"cm-rwakatsuki-patch-1"}'
{
  "message": "Repository rule violations found\n\nRequired status check \"Integration\" is expected.\n\n",
  "documentation_url": "https://docs.github.com/rest/branches/branches#merge-a-branch",
  "status": "409"
}
409 エラーとなりマージが失敗しました。期待されているステータスチェックが行われていないという旨のエラーメッセージが表示されています。
 ステータスチェックが未実施のブランチの場合ステータスチェックが未実施のブランチ cm-rwakatsuki-patch-2 で試してみます。
$ curl -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $TOKEN" \
 https://api.github.com/repos/cm-rwakatsuki/test-public/merges \
 -d '{"base":"main","head":"cm-rwakatsuki-patch-2"}'
{
  "message": "Repository rule violations found\n\nRequired status check \"Integration\" is expected.\n\n",
  "documentation_url": "https://docs.github.com/rest/branches/branches#merge-a-branch",
  "status": "409"
}
失敗したブランチと同様に、409 エラーとなりマージが失敗しました。期待されているステータスチェックが行われていないという旨のエラーメッセージが表示されています。
 ステータスチェックが成功したブランチの場合ステータスチェックが成功しているブランチ cm-rwakatsuki-patch-3 で試してみます。
$ curl -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $TOKEN" \
 https://api.github.com/repos/cm-rwakatsuki/test-public/merges \
 -d '{"base":"main","head":"cm-rwakatsuki-patch-3"}'
{
  "sha": "156fa250e344e435dbc620d2f20002ae56c92bc3",
  "node_id": "C_kwDOMj3szNoAKDE1NmZhMjUwZTM0NGU0MzVkYmM2MjBkMmYyMDAwMmFlNTZjOTJiYzM",
  // 省略
}
こちらは予想通りマージが成功しました。
プルリクエストの利用の有無に関わらず、飽くまで「ステータスチェックが成功していること」がマージの条件となるようですね。
 "Do not require status checks on creation" というチェックが新規追加されていたさて、作成済みのルールセットを眺めていると、ステータスチェックのセクションに新しいチェック項目が追加されているのを見つけました。
Do not require status checks on creation

Allow repositories and branches to be created if a check would otherwise prohibit it.
(日本語訳)

作成時にステータス チェックを必要としない

チェックによって禁止される場合は、リポジトリとブランチの作成を許可します。
とのことです。ブランチ作成時にステータスチェックを必要としないようにするオプションのようです。分かるようで分からない...。
探してみるとアップデートブログに詳細が記載されていました。

https://github.blog/changelog/2024-07-31-repository-updates-july-31st-2024/#avoid-required-status-checks-and-required-workflows-when-creating-branches
Applying status check and actions workflow rules to newly created branches has been a point of friction in rulesets. When creating a new branch will fail unless you add bypass actors or create an intermediate unprotected branch. To alleviate this friction there is a new option available prevent checks and workflows from running on new branches.
(日本語訳)

新しく作成されたブランチにステータス チェックとアクション ワークフロー ルールを適用することは、ルールセットの摩擦点となっていました。バイパス アクターを追加するか、中間の保護されていないブランチを作成しない限り、新しいブランチの作成は失敗します。この摩擦を軽減するために、新しいブランチでチェックとワークフローが実行されないようにする新しいオプションが用意されています。
ドキュメントにも記載が追加されていました。
After enabling required status checks, all required status checks must pass before collaborators can merge changes into the branch or tag. Optionally, you can select "Do not require status checks on creation" if you wish to allow branch creation regardless of the status check result.
(日本語訳)

必須ステータス チェックを有効にした後、共同作業者が変更をブランチまたはタグにマージする前に、すべての必須ステータス チェックに合格する必要があります。オプションで、ステータス チェックの結果に関係なくブランチの作成を許可する場合は、「作成時にステータス チェックを必要としない」を選択できます。
GitHub Actions などでブランチ作成を含めた自動化ワークフローを組んでいる場合に役立つオプションのようです。
 "Do not require status checks on creation" を有効にして試してみる一応今回の検証を、"Do not require status checks on creation" を有効にしたパターンでも試してみます。

$ curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/repos/cm-rwakatsuki/test-public/merges \
  -d '{"base":"main","head":"cm-rwakatsuki-patch-1"}'
{
  "message": "Repository rule violations found\n\nRequired status check \"Integration\" is expected.\n\n",
  "documentation_url": "https://docs.github.com/rest/branches/branches#merge-a-branch",
  "status": "409"
}

$ curl -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $TOKEN" \
 https://api.github.com/repos/cm-rwakatsuki/test-public/merges \
 -d '{"base":"main","head":"cm-rwakatsuki-patch-2"}'
{
  "message": "Repository rule violations found\n\nRequired status check \"Integration\" is expected.\n\n",
  "documentation_url": "https://docs.github.com/rest/branches/branches#merge-a-branch",
  "status": "409"
}
どちらも 409 エラーとなりマージが失敗しました。このオプションは飽くまでブランチの作成を許可するためのもので、作成後のブランチでステータスチェックがどうなっているかには影響しないようです。
 おわりにステータスチェックで保護されたブランチをプルリクエストではなく GitHub API を使ってマージした際の挙動を確認してみました。
プルリクエストを使わずにブランチをマージするケースは、一般的なアプリやシステムの開発で使うことは自身の経験上はあまり無かったですが、下記ディスカッションのように、OSS の開発運用などで CHANGELOG や README の更新を自動化する場合などに需要があるようです。

https://github.com/orgs/community/discussions/13836
ただ最近ステータスチェックに追加された "Do not require status checks on creation" オプションに関しては使い方がまだ把握し切れていないため、分かる方がいたらこっそり教えて下さい。
以上