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

要約

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

よくある原因

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 表示される

解決策

1. 置き場所を確認

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

サブディレクトリ配置は Workflow syntax 公式ドキュメント でも明示的に不可とされている。

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 を検討する（ただしセキュリティ上の罠が多いため、必ず公式ドキュメントの注意事項を読む）。