GitHub Actions のトリガー設定完全ガイド
akinori概要
GitHub Actions を使い始めて最初に決めるのが「いつワークフローを動かすか」です。この「いつ」を定義するのが on キーです。ここを正しく理解していないと、意図せず全ブランチで CI が走ったり、タグを push しても本番デプロイが発火しなかったりといった事故が起きます。
本記事では、GitHub Actions のトリガー（イベント）設定を入門者向けに体系的に整理します。公式の on キーで使える主要イベントと、実務でつまずきやすいポイントを一通り押さえることを目標にします。
環境
- GitHub リポジトリ（パブリック / プライベート問わず）
- ワークフローファイルは
.github/workflows/*.ymlに配置 - YAML の基本文法を理解していること
on の3つの書き方
# 1. 単一イベント
on: push
# 2. 複数イベント（配列）— フィルタは付けられない
on: [push, pull_request]
# 3. マップ形式 — イベントごとにフィルタ可能（実務の基本）
on:
push:
branches: [main]
pull_request:
branches: [main]
branches / paths / types などのフィルタを使いたいなら、3 のマップ形式を選びます。
push — ブランチ・タグへの push で発火
on:
push:
branches:
- main
- "release/**"
paths:
- "src/**"
- "package.json"
branches: 対象ブランチ。**でネストしたブランチ名にもマッチpaths: 指定パスに変更があったときだけ発火。ドキュメントのみの変更で CI を回さない用途に有効
除外は -ignore サフィックスで書きます。
on:
push:
branches-ignore: ["tmp/**"]
paths-ignore: ["docs/**", "**.md"]
なお branches と branches-ignore は同一イベント内で併用できません。組み合わせたい場合は branches 内で ! 否定パターンを使い、上から順に評価される点に注意します。
pull_request — PR に対して発火
CI の主役です。デフォルトの types は opened / synchronize / reopened です。
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
branches: [main]
paths: ["src/**"]
Draft PR の間は実行したくない場合、ジョブ側で制御します。
jobs:
test:
if: github.event.pull_request.draft == false
runs-on: ubuntu-latest
steps:
- run: echo "Draft以外で実行"
落とし穴：チェックアウトされるコード
pull_request で actions/checkout を実行すると、デフォルトでは PR のマージ結果（マージコミット）がチェックアウトされます。PR ブランチの HEAD そのものではない点に注意してください。マージ後の状態でテストする合理的な設計ですが、git log の見え方が直感と異なることがあります。
pull_request_target — 便利だが危険なイベント
フォークからの pull_request では、シークレットにアクセスできず GITHUB_TOKEN も読み取り専用になります。これは悪意ある PR がシークレットを盗むのを防ぐ安全設計です。
これを回避するのが pull_request_target ですが、扱いには最大級の注意が必要です。ベースブランチのコンテキストで実行されるためシークレットにフルアクセスでき、ここで PR 側のコードを明示的にチェックアウトして実行すると、攻撃者の任意コードをシークレット付きで実行する重大な脆弱性になります。
# ⚠️ 危険なアンチパターン
on: pull_request_target
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }} # PR側のコード
- run: npm ci && npm run build # 攻撃者コードが動きうる
pull_request_target はラベル付けや PR コメントなど「PR のコードを実行しない」用途に限定します。ビルド・テストが必要なら、原則 pull_request を使います。
schedule — 定期実行（cron）
on:
schedule:
- cron: "0 0 * * *" # 毎日 00:00 UTC（= JST 9:00）
- cron: "0 */6 * * *" # 6時間ごと
注意点は次の通りです。
- タイムゾーンは UTC 固定
- 正確な時刻に動く保証はない（負荷で遅延しうる）
- デフォルトブランチの定義でのみ動く
- 60日間活動がないと自動停止する
workflow_dispatch — 手動実行
Actions タブからボタンで実行でき、入力パラメータも渡せます。
on:
workflow_dispatch:
inputs:
environment:
description: "デプロイ先"
required: true
type: choice
options: [staging, production]
dry_run:
type: boolean
default: true
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- run: echo "対象=${{ inputs.environment }} dry_run=${{ inputs.dry_run }}"
type には string / boolean / choice / environment が使えます。
workflow_call — 再利用可能ワークフロー
共通の CI ロジックを部品化し、他のワークフローから呼び出せます。
# 呼ばれる側
on:
workflow_call:
inputs:
node-version:
type: string
default: "20"
secrets:
npm-token:
required: false
# 呼ぶ側
jobs:
call-test:
uses: ./.github/workflows/reusable-test.yml
with:
node-version: "20"
secrets: inherit
その他の主要イベント
| イベント | 発火タイミング | 主な用途 |
|---|---|---|
release |
リリース作成・公開 | 本番デプロイ、成果物公開 |
issues |
Issue の open/close/label | Issue の自動仕分け |
issue_comment |
Issue / PR コメント | コマンド起動 |
workflow_run |
別ワークフロー完了 | CI 完了後のデプロイ連鎖 |
create / delete |
ブランチ・タグの作成/削除 | タグ連動処理 |
concurrency — 多重起動の制御
トリガー設定と必ずセットで考えたい設定です。
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
CI では cancel-in-progress: true（古い実行をキャンセル）、本番デプロイでは false（途中キャンセルが危険）が定石です。
実装例：典型的な CI/CD の全体像
name: CI/CD
on:
push:
branches: [main]
tags: ["v*"]
pull_request:
branches: [main]
workflow_dispatch:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "PRとpush両方でテスト"
deploy:
needs: test
if: startsWith(github.ref, 'refs/tags/v') # タグpushのみ
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "本番デプロイ"
設計指針は「トリガー（on）はゆるく設定し、細かい分岐はジョブの if で行う」ことです。on は発火の入口、if は各ジョブの実行条件、と役割を分けると設計がすっきりします。
確認方法
- ワークフローファイルを push すると、YAML に誤りがあれば Actions タブに「Invalid workflow file」と表示される
- 実際に該当イベントを起こし、Actions タブで実行履歴を確認する
workflow_dispatchを追加しておくと、イベントを待たずにボタンから検証できる
- run: |
echo "event_name = ${{ github.event_name }}"
echo "ref = ${{ github.ref }}"
注意点
paths/branchesフィルタは push と pull_request でのみ有効（schedule/workflow_dispatchには効かない）paths-ignoreで全変更がマッチするとワークフロー自体が発火せず、必須チェックだと PR がマージ不能になることがあるscheduleはデフォルトブランチの定義でしか動かないpull_request_targetは原則避ける- 配列形式
on: [push, ...]ではフィルタを付けられない
まとめ
GitHub Actions のトリガー設定は「on に何を書くか」だけでなく、「フィルタで絞る」「if で分岐する」「concurrency で多重起動を防ぐ」までをワンセットで考えると、事故のない CI/CD が組めます。まずはシンプルに push と pull_request から始め、必要に応じて手動実行・定期実行を足していくのがおすすめです。
＼ 最新情報をチェック ／
