できない.dev

GitHub Actions のワークフローが push / PR で起動しない

ワークフローファイルの配置パス・トリガー名の typo・branches / paths フィルタのいずれかが原因で発火対象から外れている可能性が高い。
Actions タブの All workflows 一覧に名前が出るかをまず確認する。

公開: 更新:

症状できない
find .github -name '*.yml'
.github/workflow/misplaced.yml
.github/workflows/ok.yml
.github/workflows/typo.yml

2026-09-21 に local host (Windows 11 Home, Docker 29.1.3)(Node.js 22.14.0 / npm 10.9.2) で実際に打って取った出力。検証環境の詳細

要約

GitHub Actions のワークフローが起動しない場合、原因の大半は (1) YAML の置き場所、(2) on: のイベント名 typo、(3) branches: / paths: フィルタの 3 つに集約される。
順に潰せばほぼ特定できる。
最初に見るのは、Actions タブの「All workflows」一覧にワークフロー名が出ているかどうかである。

実行例

act で push イベントの対象ジョブを一覧すると、.github/workflows/ 直下に on: push で置いた ok.yml だけが表示された。
s の抜けた .github/workflow/ に置いた misplaced.yml と、イベント名を on: pushh と綴り間違えた typo.yml は、どちらも一覧に出てこなかった。

$ find .github -name '*.yml'
.github/workflow/misplaced.yml
.github/workflows/ok.yml
.github/workflows/typo.yml
$ act -l push
Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      ok      ok        ok             ok.yml         push  

— 2026-09-21 時点の出力

検証環境Node.js 22.14.0 / npm 10.9.2 / Git 2.48.1.windows.1 / 2026-09-21 検証(ほか 1 件)
検証日
実行環境
local host (Windows 11 Home, Docker 29.1.3)
バージョン
  • Node.js 22.14.0
  • npm 10.9.2
  • Git 2.48.1.windows.1
  • Docker 29.1.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 置き場所を確認

.github/
└── workflows/
    ├── ci.yml          ← OK(直下)
    └── ci/build.yml    ← 起動しない(サブディレクトリ)

置き場所は Workflow syntax for GitHub Actions(新しいタブで開く) で「ワークフローファイルはリポジトリの .github/workflows ディレクトリに置く」と定められている。

2. イベント名を snake_case で書き直す

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

pull-request / pullrequest は無効である。
workflow_dispatch、schedule、release 等もすべて snake_case で揃える。

3. フィルタを一時的に外して切り分け

on:
  push: {}
  pull_request: {}

これで起動するなら、原因はフィルタにある。
branches: と paths: を 1 つずつ戻し、どちらが除外しているかを特定する。

4. Actions タブで「All workflows」を確認

リポジトリの Actions タブにワークフロー名が一覧表示されない場合、GitHub 側にすら YAML が認識されていない。
Settings → Actions → General で Actions permissions が Disable actions になっていないかも確認する。

5. fork PR の場合

外部 fork からの PR では secrets は渡されない。
書き込みを要するワークフローは pull_request_target(新しいタブで開く) を検討する(ただしセキュリティ上の罠が多いため、必ず公式ドキュメントの注意事項を読む)。

よくある原因

  1. .github/workflows/ci/build.yml のようにサブディレクトリに置いている。
    ワークフローは .github/workflows/ の 直下 でないと検出されない。
  2. on: pull-request: on: pullrequest: のようにイベント名を typo している。
    正しくは pull_request と書く。
  3. branches: [main] を指定しているが、リポジトリのデフォルトブランチが master のままになっている。
  4. paths: ['src/**'] のみを許可しているのに、ドキュメント変更だけの PR で起動を期待している。
  5. 外部 fork からの PR では secrets は空で、GITHUB_TOKEN も read のみになる。
    そのため、シークレット参照のあるジョブが skip と表示される。