GitHub Actions の再実行上限は 50 回です。2026年4月10日にGitHubが公開した changelog と最新ドキュメントでは、同じ workflow run の再実行は最大50回までと明記されました。ワークフロー全体の再実行だけでなく、失敗ジョブだけの再実行、特定ジョブだけの再実行もこの上限に含まれます。上限を超えると、annotation 付きの failed check suite になります。 (The GitHub Blog)
この変更で大きく変わるのは、不安定なワークフローのデバッグの考え方です。これからは「通るまで何度も rerun する」より、少ない再実行回数で原因を切り分ける運用のほうが重要になります。この記事では、GitHub Actions の再実行上限 50 の正確な意味と、フレーキーなワークフローを実務でどう扱うべきかを整理します。 (The GitHub Blog)
GitHub Actions の再実行上限 50 とは
今回の 50 回 cap は changelog の告知だけでなく、GitHub Actions の rerun ドキュメントと limits ドキュメントにも反映されています。実務では、「同じ workflow run を、初回実行から30日以内に、最大50回まで再実行できる」と理解しておくと判断しやすいです。再実行できるのは、リポジトリに write 権限を持つユーザーです。 (GitHub Docs)
先に押さえたい誤解ポイント
- 50回の単位は workflow ファイル全体ではありません。 上限は、同じ
workflow runに対する再実行回数です。リポジトリ全体や workflow 定義ファイル全体の累計回数ではありません。 (GitHub Docs) - 失敗ジョブだけの再実行は別枠ではありません。 full rerun も、失敗ジョブだけの rerun も、特定 job の rerun も、同じ 50 回上限に含まれます。 (The GitHub Blog)
- 権限は rerun を押した人のものに切り替わりません。 GitHub の公式 docs では、rerun は「再実行を開始した人」ではなく「元の workflow を起動した actor」の権限を使うと説明されています。管理者が rerun しても、権限不足がそのまま残ることがあります。 (GitHub Docs)
- rerun しても対象のコミットは変わりません。 rerun は元のイベントと同じ
GITHUB_SHAとGITHUB_REFを使います。つまり、コードや workflow を直した後の確認には、古い run の rerun より新しい runを使うほうが適切です。 (GitHub Docs)
不安定なワークフローのデバッグはどう変わるか
GitHub は今回の上限追加について、一部の自動化が同じ workflow に対して数百回の retry を試み、システム負荷を増やしていたことへの対応だと説明しています。要するに、GitHub Actions 側も「力技の再試行」を前提にしない方向へ明確に舵を切った、ということです。 (The GitHub Blog)
| ありがちな運用 | これから優先したい運用 |
|---|---|
| とりあえず workflow 全体を rerun する | まず失敗ジョブだけ、必要なら特定 job だけを rerun する |
| 同じ run を延々と使い続ける | 数回で原因を分類し、修正後は新しい run に切り替える |
| ログが薄いまま再実行を重ねる | debug logging とログ保存を先に行う |
| bot で無限に再試行する | チーム側で小さめの内部上限を設けて止める |
特に重要なのは、rerun で確認できるのは「同じ条件でもう一度試した結果」だという点です。rerun は同じ SHA/REF と元の actor 権限を引き継ぐので、「たまたま落ちたのか」を見るには向いていますが、「修正後に改善したか」を見る用途には向きません。後者を見たいなら、新しい run を作るべきです。 (GitHub Docs)
影響が出やすいケース
フレーキーテストが多いリポジトリ
E2E テストや統合テストが不安定なチームは、今回の変更の影響を受けやすいです。これまで「もう一回 rerun したら通る」で済ませていたワークフローほど、50 回 cap の存在が効いてきます。実務では、まず Re-run failed jobs や特定 job の rerun で範囲を絞り、同じ SHA で同じ箇所が連続して落ちるなら、3回目以降は rerun より原因調査に時間を使うほうが効率的です。 (GitHub Docs)
self-hosted runner や外部サービス依存が強いワークフロー
ランナーの一時不調、ネットワークの瞬断、外部 API の揺らぎが原因なら、再実行そのものは有効です。ただし、回数を重ねる前に追加ログを取るのが先です。GitHub は ACTIONS_RUNNER_DEBUG=true と ACTIONS_STEP_DEBUG=true をシークレットまたは変数で設定する方法を案内しており、runner diagnostic logs はダウンロードしたログアーカイブ内の runner-diagnostic-logs フォルダから確認できます。 (GitHub Docs)
権限・シークレット・ブランチ条件の問題
認証エラーや権限不足は、rerun を何度重ねても解決しにくい代表例です。GitHub の docs どおり、rerun は元の actor の権限で動くため、「権限のある人が押し直せば通るはず」は通用しないことがあります。このタイプは設定や権限を直した後、workflow を手動実行するか、通常のトリガーで新しい runを作るほうが確実です。 (GitHub Docs)
CLI や REST API で再試行を自動化しているケース
gh run rerun や REST API の rerun エンドポイントで retry を自動化しているチームも要注意です。GitHub は今回の上限を、まさに「数百回の retry を試す automation」への対応として追加しています。無限ループや長い while ループのままでは、最終的に 50 回 cap に達して failed check suite になるので、bot 側に打ち止め条件とアラートを入れるべきです。 (The GitHub Blog)
上限時代の実践的なデバッグ手順
不安定な GitHub Actions を扱うときは、次の順番で動くと無駄な rerun を減らしやすくなります。
| 状況 | 最初の一手 | 避けたい動き |
|---|---|---|
| 一時的な失敗に見える | 失敗ジョブだけを再実行 | いきなり workflow 全体を連打する |
| 詳細が足りない | debug logging を有効にする | ログを残さず rerun を重ねる |
| コードや workflow を直した | 新しい run を作る | 古い run の rerun に固執する |
| 権限エラーが出た | 権限・secret 設定を確認する | 管理者が何度も rerun する |
| 自動再試行を使っている | 内部上限を小さく設ける | 50 回 cap まで使い切る前提で回す |
過去 attempt を先に見比べる
GitHub Actions では、workflow run の画面で Latest ドロップダウンから過去の run attempt を見返せます。ログは UI 上で検索でき、必要ならログアーカイブもダウンロードできます。ここで一つ見落としやすいのが、部分 rerun のログアーカイブには rerun した job しか入らないことです。全体像を見たいなら、前の attempt のログもあわせて保存してください。 (GitHub Docs)
1回目の rerun から debug logging を使う
原因が見えないのに rerun を重ねるのは、50 回 cap の時代では非効率です。GitHub の UI では rerun 時に debug logging を有効化でき、継続的に詳しいログを取りたいなら ACTIONS_RUNNER_DEBUG=true と ACTIONS_STEP_DEBUG=true をリポジトリのシークレットまたは変数に設定できます。特に runner 側の問題を疑うときは、通常ログより diagnostic logs のほうが役に立ちます。 (GitHub Docs)
全体 rerun ではなく、failed jobs か specific job から始める
GitHub は、workflow 全体の rerun だけでなく、失敗ジョブだけの rerun と特定 job の rerun を公式にサポートしています。フレーキーなワークフローほど、最初から workflow 全体を回し直すより、狙った job だけを再現したほうが切り分けが早いです。 (GitHub Docs)
# 失敗ジョブだけを追加ログ付きで再実行
gh run rerun RUN_ID --failed --debug
# 特定ジョブだけを追加ログ付きで再実行
gh run rerun --job JOB_ID --debug
# 修正後は新しい workflow run を作る
gh workflow run WORKFLOW --ref BRANCH上の CLI は、GitHub 公式 docs に載っている代表的な操作です。gh workflow run を使うには workflow 側で workflow_dispatch を設定しておく必要があり、手動実行の対象 workflow は default branch 上にある必要があります。 (GitHub Docs)
修正後の確認は「新しい run」に切り替える
コードや workflow を変更したあとに見たいのは、「古い条件でもう一度どうなるか」ではなく、「修正後の状態でどうなるか」です。rerun は元の GITHUB_SHA と GITHUB_REF を使うので、修正確認には向きません。ここで古い run を使い続けると、調べている対象と直した対象がずれていくのが実務上の失敗パターンです。修正後は新しい run に切り替えてください。 (GitHub Docs)
自動再試行は GitHub の上限より先に止める
GitHub 側の上限が 50 回だからといって、チーム側の retry 上限まで 50 にする必要はありません。実務では、3〜5回程度で内部打ち止めにして、Slack 通知や Issue 起票に切り替えるほうが運用しやすいことが多いです。GitHub が cap を導入した背景自体が「過剰な automation retry」なので、bot には小さめの内部上限、ログ保存、担当者へのエスカレーションをセットで入れるのが安全です。 (The GitHub Blog)
まず見直したい運用ルール
- rerun のデフォルトを workflow 全体ではなく failed jobs にする。 (GitHub Docs)
- 原因不明の失敗では、2回目の rerun までに debug logging を入れる。 (GitHub Docs)
- 主要な検証 workflow には
workflow_dispatchを用意し、修正後に新しい run を作りやすくする。 (GitHub Docs) - 部分 rerun を使うチームほど、attempt ごとのログ保存を手順化する。 (GitHub Docs)
今回の GitHub Actions の再実行上限 50 は、単なる制限ではありません。デバッグを「回数で押し切る」やり方から、「ログを取り、範囲を絞り、新しい run に切り替える」やり方へ変えるための分かりやすい境界線です。まずは、再実行を自動化している bot やスクリプトの打ち止め条件を確認し、主要 workflow に workflow_dispatch と debug logging の手順を用意し、失敗ジョブ単位の rerun をチーム標準にしてください。そこまで整えるだけで、50 回という数字に振り回されず、フレーキーな原因にずっと早くたどり着けます。 (The GitHub Blog)
コメント