GitHub Actions ワークフローが実行されない時の解決策
GitHub Actions のワークフローが思ったように実行されない場合、原因は様々な要因が考えられます。本記事では、よくある問題とその解決方法を網羅的に解説します。
前提条件
- GitHub リポジトリへのアクセス権限
- 基本的な GitHub Actions の知識
- YAML ファイルの記述経験
よくある原因と解決策
1. ブランチ名の不一致
最も多い原因の一つが、ワークフローファイルで指定したブランチ名と実際のブランチ名が一致していない場合です。
# 間違った例（master だが実際は main ブランチ）
on:
push:
branches:
- master
# 正しい例
on:
push:
branches:
- main重要
2020年10月以降、GitHub のデフォルトブランチ名は master から main に変更されました。既存のコードをコピーする場合は注意が必要です。
2. ワークフローファイルの配置場所の問題
ワークフローファイルは正しい場所に配置する必要があります。
正しい配置:
.github/
└── workflows/
└── your-workflow.ymlよくある間違い:
.github/workspaces/フォルダに配置.github/workflows/内のサブフォルダに配置- ファイル名にスペースや特殊文字を含む
- フォルダ名に余分なスペース（例:
.github / workflows）
注意
ワークフローファイルは .github/workflows/ 直下に配置する必要があります。サブフォルダ内のファイルは認識されません。
3. paths 設定の問題
特定のパスのみでワークフローを実行するように設定している場合、そのパス外の変更ではワークフローは実行されません。
# この設定では、packages/container/ 以下の変更のみで実行される
on:
push:
branches:
- main
paths:
- 'packages/container/**'パス制限を解除するか、ワークフローファイル自身のパスを含める必要があります。
4. ブランチ名のパターンマッチングの問題
ブランチ名のパターンマッチングでは正規表現ではなくグロブパターンを使用します。
# 間違った例（正規表現のように記述）
on:
push:
branches:
- 'TTG-.*'
- 'FRD-.*'
# 正しい例（グロブパターン）
on:
push:
branches:
- 'TTG-*'
- 'FRD-*'5. 特殊文字を含むブランチ名
ブランチ名に +, ?, !, *, ** などの特殊文字が含まれている場合、適切にエスケープする必要があります。
6. ワークフローファイルがリポジトリに存在しない
.gitignore ファイルで .* のような設定をしている場合、.github フォルダ全体が無視されてしまう可能性があります。
7. 権限設定の問題
リポジトリ設定でワークフローの実行権限が適切に設定されているか確認してください。
確認場所: リポジトリ設定 → Actions → General → Workflow permissions
高度な問題と解決策
ワークフローが自動的に無効化されている場合
90日間プロジェクトに更新がない場合、ワークフローは自動的に無効化されることがあります。この場合、各ワークフローのページで警告をクリックして再有効化する必要があります。
フォークされたリポジトリでのワークフロー
他のリポジトリをフォークした場合、セキュリティ上の理由からワークフローはデフォルトで無効化されています。Actions タブから明示的に有効化する必要があります。
コミットメッセージによるスキップ
コミットメッセージに [skip ci], [ci skip], [no ci], [skip actions], [actions skip] のいずれかが含まれている場合、ワークフローは実行されません。
コンフリクトの問題
プルリクエストでベースブランチとのコンフリクトがある場合、特定のワークフローは実行されない可能性があります。
GITHUB_TOKEN の制限
リポジトリの GITHUB_TOKEN を使用するアクションが別のワークフローをトリガーする場合、セキュリティ上の理由でそのワークフローは実行されません。この場合は個人アクセストークン（PAT）を使用する必要があります。
- uses: actions/checkout@v2
with:
token: ${{ secrets.PAT }}トラブルシューティングのチェックリスト
- ブランチ名の確認: ワークフローで指定したブランチ名と実際のブランチ名が一致しているか
- ファイル配置: ワークフローファイルが
.github/workflows/直下にあるか - パス設定:
paths設定が意図したものか - 特殊文字: ブランチ名やファイル名に問題のある特殊文字が含まれていないか
- gitignore: ワークフローファイルが無視されていないか
- 権限設定: リポジトリのワークフロー権限が適切か
- コミットメッセージ: スキップ指示が含まれていないか
- GitHub Status: GitHub Status でサービス障害がないか確認
- 新規リポジトリ: 新規リポジトリの場合は5-10分待つ
まとめ
GitHub Actions のワークフローが実行されない場合、まずは基本的な設定ミスがないか確認することが重要です。本記事で紹介したチェックリストを順番に確認することで、ほとんどの問題は解決できるでしょう。それでも解決しない場合は、GitHub のサービス状態やより詳細なログ確認が必要になる場合があります。
最終手段
どうしても原因がわからない場合は、GitHub の Actions タブからサンプルのワークフローを生成して、それを基に自分のワークフローを比較してみることをおすすめします。