GitHub ActionsのYAMLファイルが存在していても、pushやscheduleの条件を満たさなければワークフローは始まりません。特に多い原因は、ワークフローの無効化、onの設定ミス、branches・pathsの絞り込み、既定ブランチにないスケジュール設定、コミットのスキップ指示、GITHUB_TOKENを使った自動pushです。
最初に確認すべきなのは、ワークフロー実行そのものが作成されていないのか、実行は作成されたがジョブがスキップされたのかです。この2つでは、調べる場所がまったく異なります。([GitHub Docs][1])
GitHub Actionsが実行されないときのイベント・条件・トークン確認
GitHub Actionsが動かないときは、いきなりYAML全体を書き直すのではなく、Actions画面の状態から原因を切り分けます。
| Actions画面の状態 | 主に確認する項目 |
|---|---|
| ワークフロー実行が1件も作成されていない | on、ブランチ、パス、スキップ指示、GITHUB_TOKEN |
実行はあるがジョブがSkipped | if、needs、式の評価結果 |
Awaiting approvalと表示される | Pull Requestの承認ポリシー |
QueuedやPendingのまま | ランナー、同時実行制御、環境の承認 |
| ワークフロー自体がActions画面に出ない | ファイルの場所、拡張子、既定ブランチ、YAML構文 |
実行履歴がない場合はイベント発火前の問題、Skippedの場合はジョブ条件の問題と考えると、調査範囲を大きく絞れます。
YAMLファイルの場所とワークフローの有効状態を確認する
GitHub Actionsのワークフローファイルは、リポジトリ内の次の場所に保存する必要があります。
.github/workflows/拡張子は.ymlまたは.yamlです。たとえば、次のような配置にします。
.github/
└── workflows/
└── ci.ymlworkflow/ci.ymlや.github/action/ci.ymlなど、別のディレクトリに置いてもワークフローとして認識されません。ローカルにファイルを作成しただけで、対象ブランチへコミット・pushしていないケースにも注意してください。([GitHub Docs][2])
現在のコミットにあるワークフローファイルは、次のコマンドで確認できます。
git ls-tree -r HEAD --name-only .github/workflows既定ブランチ上のファイルを確認する場合は、リモートの情報を更新してから確認します。
git fetch origin
git ls-tree -r origin/main --name-only .github/workflows既定ブランチがmasterなど別の名前なら、origin/mainを実際のブランチ名に置き換えます。
ワークフローが無効になっていないか確認する
YAMLファイルが残っていても、ワークフロー自体が無効になっているとイベントには反応しません。
リポジトリの「Actions」を開き、対象ワークフローのメニューを確認してください。「Enable workflow」が表示されている場合、そのワークフローは無効です。
あわせて、リポジトリの「Settings」から「Actions」→「General」を開き、GitHub Actionsの実行が許可されているか確認します。OrganizationやEnterprise配下のリポジトリでは、上位の管理ポリシーにより設定が固定されていることがあります。([GitHub Docs][3])
また、公開リポジトリでは、一定期間リポジトリに活動がない場合にスケジュール実行が自動的に無効化されることがあります。フォークした公開リポジトリでも、スケジュールワークフローが初期状態で無効になっている場合があります。([GitHub Docs][3])
onの設定を最小構成にして切り分ける
ワークフローを開始するイベントは、YAMLのonで指定します。
複雑な条件を設定している場合は、一時的に最小構成へ切り替えると原因を見つけやすくなります。
name: Trigger check
on:
push:
workflow_dispatch:
schedule:
- cron: '17 * * * *'
timezone: 'Asia/Tokyo'
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Show trigger information
run: |
echo "event=${{ github.event_name }}"
echo "ref=${{ github.ref }}"
echo "sha=${{ github.sha }}"この例では、次の3つの方法で実行できます。
- ブランチへのpush
- Actions画面からの手動実行
- 毎時17分のスケジュール実行
workflow_dispatchを追加して手動実行が成功するなら、YAMLの基本構造とジョブ自体は動作しています。その場合は、pushまたはschedule固有の条件を重点的に確認します。
なお、workflow_dispatchによる実行には、ワークフローファイルが既定ブランチに存在している必要があります。「Run workflow」ボタンが表示されない場合は、既定ブランチ上のファイル、ワークフローの有効状態、実行権限を確認してください。([GitHub Docs][4])
pushで実行されない場合はbranchesとpathsを確認する
pushイベントにbranchesやpathsを設定すると、すべての条件に一致した場合だけワークフローが始まります。
たとえば、次の設定では、mainブランチへpushし、なおかつsrcまたはワークフローファイルに変更がある場合だけ実行されます。
on:
push:
branches:
- main
paths:
- 'src/**'
- '.github/workflows/**'この設定でREADME.mdだけを変更しても、pathsに一致しないため実行されません。developブランチへpushした場合も、branchesに一致しないため実行されません。
branchesとpathsは「どちらかを満たせばよい」というOR条件ではなく、両方を満たす必要があるAND条件です。([GitHub Docs][2])
よくあるフィルター設定の見落とし
| 設定 | 実行されない例 |
|---|---|
branches: [main] | developやmasterへのpush |
paths: ['src/**'] | docsやREADME.mdだけの変更 |
tags: ['v*'] | 通常のブランチへのpush |
paths-ignore: ['docs/**'] | 変更ファイルがすべてdocs配下 |
branches-ignore: [release/**] | release/v1へのpush |
既定ブランチ名がmainなのに、古い設定のままmasterを指定しているケースも少なくありません。リポジトリの「Settings」→「Branches」などで、実際の既定ブランチ名を確認してください。
除外パターンは記述順にも注意する
!を使った否定パターンでは、パターンを記述する順序が判定に影響します。
on:
push:
paths:
- '**'
- '!docs/**'
- 'docs/important.md'この例では、原則としてdocs配下を除外しつつ、docs/important.mdを再び対象に含めています。後から一致したパターンによって、対象への追加や除外が変わるためです。([GitHub Docs][2])
大量の変更を含むpushにも注意する
パスフィルターの判定対象には上限があります。非常に多くのファイルを一度に変更した場合、対象ファイルが判定対象に含まれず、期待したワークフローが始まらないことがあります。
GitHubのドキュメントでは、差分生成時に確認されるファイル数に制限があることが示されています。大量変更時だけ再現する場合は、pushを小さく分割するか、パス条件を一時的に外して確認してください。([GitHub Docs][2])
scheduleで実行されない場合は既定ブランチと時刻を確認する
scheduleイベントには、通常のpushとは異なる条件があります。
- ワークフローファイルが既定ブランチに存在する必要がある
- 既定ブランチ上の最新コミットが実行対象になる
- ワークフローが有効になっている必要がある
- 指定時刻どおりの開始は保証されない
- 公開リポジトリでは、長期間活動がないと無効化される場合がある
作業ブランチにscheduleを追加しただけでは、そのスケジュールは実行されません。まず既定ブランチへマージされているか確認してください。([GitHub Docs][4])
タイムゾーンを明示する
タイムゾーンを指定しないcron設定は、UTCを基準として解釈されます。日本時間で実行したい場合は、現在のGitHub ActionsではIANA形式のタイムゾーンを明示できます。
on:
schedule:
- cron: '30 9 * * *'
timezone: 'Asia/Tokyo'この設定は、日本時間の毎日9時30分に実行する指定です。
タイムゾーン指定を使わない場合、日本時間9時30分はUTCの0時30分として指定します。
on:
schedule:
- cron: '30 0 * * *'スケジュールの最短実行間隔は5分です。([GitHub Docs][2])
毎時0分を避ける
次のように毎時0分を指定すると、利用が集中する時間帯と重なりやすくなります。
on:
schedule:
- cron: '0 * * * *'GitHubは、毎時の開始時刻付近など負荷が高い時間帯では、スケジュール実行が遅延する可能性があり、状況によってはキューに入ったジョブが実行されない場合もあると案内しています。
毎時実行が必要でも、次のように17分や23分などへずらす方が安定しやすくなります。
on:
schedule:
- cron: '17 * * * *'
timezone: 'Asia/Tokyo'scheduleは指定した分に必ず開始されるリアルタイム処理ではありません。数分の遅延を許容できない処理には、外部スケジューラーや明示的なAPI実行など、別の仕組みも検討する必要があります。([GitHub Docs][1])
コミットメッセージのスキップ指示を確認する
pushやpull_requestで実行されない場合は、コミットメッセージにスキップ指示が含まれていないか確認します。
GitHub Actionsでは、次の文字列がコミットメッセージに含まれると、対象ワークフローがスキップされます。
[skip ci][ci skip]
[no ci]
[skip actions]
[actions skip]
コミットメッセージの末尾に、次のトレーラーを指定した場合も同様です。
skip-checks:trueまたは、
skip-checks: trueこれらの指定はpushとpull_requestに影響しますが、scheduleには適用されません。([GitHub Docs][5])
スキップ指示を削除するために過去のコミットを書き換える必要はありません。新しいコミットを、スキップ指示なしでpushすれば再判定できます。
変更内容がない場合は、空コミットを作成できます。
git commit --allow-empty -m "Run GitHub Actions"
git pushブランチ保護でGitHub Actionsのチェックを必須にしている場合、スキップされたチェックがPendingのまま残り、Pull Requestをマージできないことがあります。その場合も、スキップ指示を含まない新しいコミットをpushしてチェックを実行します。([GitHub Docs][5])
GITHUB_TOKENでpushした変更は次のワークフローを起動しない
GitHub Actions内でファイルを更新し、その変更をgit pushしている場合は、使用している認証情報を確認してください。
リポジトリに自動発行されるGITHUB_TOKENを使って発生したイベントは、原則として新しいワークフロー実行を作成しません。これは、ワークフローが自身を繰り返し起動して無限ループになることを防ぐための動作です。([GitHub Docs][6])
たとえば、次の流れでは2つ目のワークフローが始まらないことがあります。
- ワークフローAがリポジトリをチェックアウトする
- ワークフローAがファイルを自動生成する
- ワークフローAが
git pushする on: pushのワークフローBが始まることを期待する- pushに
GITHUB_TOKENが使われているため、ワークフローBは始まらない
actions/checkoutは、後続のGitコマンドで利用できる認証情報を既定で保持します。そのため、別の認証情報を明示していなければ、後続のgit pushがGITHUB_TOKENを利用している可能性があります。([GitHub][7])
対処方法を目的別に選ぶ
| 目的 | 推奨する方法 |
|---|---|
| 自動生成後に続けてデプロイしたい | 同じワークフローの後続ジョブとして実行する |
| 別ワークフローを明示的に呼び出したい | workflow_dispatchまたはrepository_dispatchを使う |
| 通常のpushイベントとして扱う必要がある | GitHub AppのインストールトークンやPATを検討する |
| 無限ループを防ぎたい | 実行元、変更パス、コミット内容を条件で制限する |
workflow_dispatchとrepository_dispatchは、GITHUB_TOKENによるイベント抑制の例外として扱われます。ただし、呼び出される側のワークフローファイルが既定ブランチに存在しているか、トークンに必要な権限があるかも確認してください。([GitHub Docs][6])
PATを使えば必ずよいわけではありません。単に処理を連続させたいだけなら、同じワークフロー内でジョブを分ける方が、権限管理とトラブル調査が容易です。
PATやGitHub Appのトークンを使う場合は、必要最小限の権限に絞り、GitHub Secretsなどで管理します。トークン、秘密鍵、回復コードをYAMLへ直接記載したり、ログや画面キャプチャへ表示したりしないでください。
Pull Requestの承認待ちと非発火を混同しない
フォークされたリポジトリからのPull Requestなどでは、ワークフローが自動的に始まらず、管理者の承認を待つことがあります。
この場合は、イベントが発生していないのではありません。Pull RequestやActions画面にAwaiting approvalなどの表示があり、権限を持つメンテナーが内容を確認して承認すると実行されます。([GitHub Docs][8])
判断の目安は次のとおりです。
- 実行履歴や承認待ち表示がある：承認ポリシーの問題
- 実行履歴自体がない：
on、フィルター、スキップ指示、トークンを確認 - 実行履歴はあるがジョブが
Skipped：ifやneedsを確認
現在のGitHub Actionsでは、GITHUB_TOKENを使った処理によってPull Requestが作成・更新された場合、一部のPull Requestイベントが承認待ちとして作成される特別な扱いもあります。一方で、すべてのPull Request操作が新しい実行を作成するわけではありません。単純に「自動作成したPRだから実行される」と判断せず、イベント種別とActions画面の状態を確認してください。([GitHub Docs][6])
ジョブがSkippedならEvaluating・Expanded・Resultを確認する
ワークフロー実行は作成されているものの、特定のジョブがSkippedになっている場合は、トリガーではなくジョブ条件を調べます。
GitHubの診断ログでは、条件式について次の情報を確認できます。
Evaluating：評価対象となった式Expanded：コンテキスト値を展開した後の式Result：最終的な評価結果
確認手順は次のとおりです。
- リポジトリの「Actions」を開く
- 対象のワークフロー実行を開く
- ログアーカイブをダウンロードする
- 展開したフォルダーから対象ジョブの
system.txtを開く Evaluating、Expanded、Resultを検索する
Expandedを見ると、github.refなどが実際にどの値へ置き換えられたか分かります。条件式が見た目どおりに評価されない場合に有効です。([GitHub Docs][1])
github.refはブランチ名だけではない
次の条件は、通常は成立しません。
jobs:
build:
if: github.ref == 'main'github.refには、単純なmainではなく、完全な参照名が入るためです。ブランチへのpushなら、次のように指定します。
jobs:
build:
if: github.ref == 'refs/heads/main'タグの場合は、次の形式です。
refs/tags/v1.0.0Pull Requestでは、github.refが次のような値になる場合があります。
refs/pull/123/mergePull Requestのマージ先ブランチを判定したい場合は、イベントに応じてgithub.base_refを利用します。
jobs:
test:
if: github.event_name == 'pull_request' && github.base_ref == 'main'github.refの値はイベントによって変わるため、push用の条件をそのままPull Requestへ流用しないことが重要です。([GitHub Docs][9])
needsで依存する前段ジョブも確認する
次のようにジョブの依存関係を設定している場合、前段のbuildが失敗またはスキップされると、後続のdeployもスキップされます。
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: ./build.sh
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- run: ./deploy.shdeployだけを見ても原因が分からない場合は、needsで指定された前段ジョブから順に確認してください。([GitHub Docs][2])
デバッグのためにコンテキスト全体をログへ出力する方法もありますが、githubコンテキストにはトークンなどの機密性が高い情報が含まれます。共有するログでは、github.event_nameやgithub.refなど必要な項目だけを個別に出力する方が安全です。([GitHub Docs][9])
症状別に確認場所を絞り込む
| 症状 | 最初に確認する場所 |
|---|---|
| YAMLを追加したのにActionsに表示されない | .github/workflows、拡張子、コミット先 |
| pushしても実行履歴がない | on.push、branches、paths、スキップ指示 |
| 自動更新のpushだけ実行されない | GITHUB_TOKEN、checkout後の認証情報 |
| scheduleだけ実行されない | 既定ブランチ、有効状態、cron、タイムゾーン |
| 毎時0分の実行が遅れる | cronの分を0以外へ変更 |
| 手動実行は成功する | push・schedule固有の条件を確認 |
| Pull Requestが承認待ち | Actionsの承認ポリシー |
ジョブがSkipped | system.txtのExpandedとResult |
| 後続ジョブだけスキップされる | needsで指定した前段ジョブ |
| 必須チェックがPendingのまま | スキップ指示やパスフィルター |
最短の順番で原因を切り分ける
GitHub Actionsが実行されない場合は、次の順序で調べると効率的です。
- Actions画面で「実行履歴なし」「Skipped」「承認待ち」を区別する
- YAMLが
.github/workflowsにあり、対象ブランチへpush済みか確認する - ワークフローとリポジトリのGitHub Actionsが有効か確認する
workflow_dispatchを追加し、手動実行できるか確認するon.pushのbranches・tags・pathsを確認する- コミットメッセージのスキップ指示を確認する
scheduleなら既定ブランチ、タイムゾーン、実行時刻を確認する- 自動pushなら
GITHUB_TOKENを使っていないか確認する - ジョブが
Skippedなら診断ログのExpandedとResultを確認する - Pull Requestなら承認待ちポリシーを確認する
特に重要なのは、YAMLがあることと、イベント条件が成立していることは別だと理解することです。手動実行を基準点にして、イベント、フィルター、認証トークンの順に条件を戻していけば、原因を再現可能な形で特定できます。
[1]: https://docs.github.com/en/actions/how-tos/troubleshoot-workflows “Troubleshooting workflows – GitHub Docs”
[2]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax “Workflow syntax for GitHub Actions – GitHub Docs”
[3]: https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow “Disabling and enabling a workflow – GitHub Docs”
[4]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows “Events that trigger workflows – GitHub Docs”
[5]: https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs “Skipping workflow runs – GitHub Docs”
[6]: https://docs.github.com/en/actions/concepts/security/github_token “GITHUB_TOKEN – GitHub Docs”
[7]: https://github.com/actions/checkout “GitHub – actions/checkout: Action for checking out a repo · GitHub”
[8]: https://docs.github.com/en/actions/how-tos/manage-workflow-runs/approve-runs-from-forks “Approving workflow runs from forks – GitHub Docs”
[9]: https://docs.github.com/en/actions/reference/workflows-and-actions/contexts “Contexts reference – GitHub Docs”
コメント