GitHub Actions 入門：YAML ワークフローの基礎とトリガー設定
深夜3時、画面に映る赤いエラーメッセージが眩しすぎて、キーボードを壊したくなった経験はありませんか？
ローカルでは問題なく動いていたコードが、GitHub にプッシュすると失敗する。あの YAML ファイル、6回も修正したのに、毎回インデントの問題。当時は「コードを書くより難しいじゃないか」と思いました。
実は GitHub Actions 自体は複雑ではありません。難しいのはドキュメントの方です。いきなり数百ページの設定説明を渡されて、目が回りそうになります。この記事では、最もシンプルな方法で YAML ワークフローのコア構造を理解してもらいます。
この記事で学べること：
- YAML ファイルの4つのコアフィールドと、それぞれの役割
- 8種類のよく使うトリガーの設定方法と使用シーン
- そのままコピーして使える完全なワークフローテンプレート
- 私が踏んだ落とし穴と、その回避方法
準備はできましたか？始めましょう。
YAML ワークフローファイル：4つのコアフィールド
正直に言うと、GitHub Actions を使い始めた頃、.github/workflows ディレクトリにある YAML ファイルを見た時、まるで暗号解読をしているような気分でした。インデントの山、コロンだらけ、スペースを1つ間違えれば全部壊れる。
その後、気づいたのです。実はこれ、4つのコア部分しかないと。この4つを理解すれば、あとは装飾のようなものです。
name：ワークフローに名前をつける
このフィールドは最もシンプルですが、多くの人が（私を含めて）最初は無視しがちです。
name: CI for Node.js Appname は、GitHub Actions タブで表示されるワークフローの名前です。コードをプッシュした後、リポジトリの Actions ページを開くと、その名前が表示されます。
命名のコツは、プロジェクト名 + 機能説明です。例えば MyApp CI や Backend Deploy のように。こうすれば、ワークフローが増えても、一目で目的のものが見つかります。
このフィールドは省略可能です。書かない場合、GitHub はファイル名を使用します。ただ、ファイル名は通常英語の略語なので、視認性があまり良くありません。
on：いつトリガーするか
on はワークフロー全体の「スイッチ」です。GitHub に「どのような場合にこのワークフローを実行するか」を伝えます。
最もシンプルな書き方：
on: pushこれは、「コードがプッシュされたら、トリガーする」という意味です。
ただ、実際のプロジェクトでは、より細かい制御が必要です。例えば main ブランチにプッシュされた時だけ実行する：
on:
push:
branches: [main]または、Pull Request が作成された時にもトリガーしたい場合：
on:
push:
branches: [main]
pull_request:
branches: [main]トリガーは GitHub Actions の真髄です。後ほど、8種類のよく使うシーンを詳しく解説します。ここでは、on がワークフローの「実行タイミング」を決めるということを覚えておけば十分です。
jobs：何をするかを定義
jobs はワークフローの本体で、「具体的に何のタスクを実行するか」を定義します。
1つのワークフローには複数の job を含めることができ、デフォルトでは並列実行されます。各 job は実行環境を指定する必要があり、runs-on フィールドを使用します：
jobs:
build:
runs-on: ubuntu-latest
steps:
# ...ステップリストこのコードは build という名前の job を定義し、GitHub が提供する最新版の Ubuntu で実行されます。
ワークフローに複数の job がある場合、needs フィールドで依存関係を定義できます：
jobs:
test:
runs-on: ubuntu-latest
# ... テストステップ
deploy:
needs: test # test が完了してから実行
runs-on: ubuntu-latest
# ... デプロイステップこうすると、deploy は test が完了してから開始されます。もし test が失敗したら、deploy は実行されません。
steps：具体的な実行ステップ
steps は job 内の最小実行単位で、コマンドや Action が順番に実行されます。
各ステップには2つの書き方があります：
1. run でコマンドを実行：
steps:
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm testrun の後には、ターミナルで実行するコマンドを書きます。ローカルでコマンドを打つのと同じです。
2. uses で Action を呼び出す：
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'uses は GitHub Actions の強力な機能です。誰かが作った Action をそのまま使えます。例えば、actions/checkout@v4 はコードをチェックアウトし、actions/setup-node@v4 は Node.js 環境をセットアップします。
with は Action にパラメータを渡します。上の例では node-version: '20' で、「Node.js 20 を使う」ことを指定しています。
4つのフィールドの説明は以上です。想像よりシンプルだったのではないでしょうか？
トリガー完全ガイド：8種類のよく使うシーン
前述の on フィールドがトリガーのタイミングを決めます。GitHub Actions は数十種類のトリガーをサポートしていますが、正直なところ、よく使うのは限られています。
各トリガーの使用シーンを素早く理解できる表をまとめました：
| トリガー | 典型的なシーン | 設定例 |
|---|---|---|
push | ブランチへのコードプッシュ | on: push: branches: [main] |
pull_request | PR の作成または更新 | on: pull_request: types: [opened, synchronize] |
schedule | 定期実行（Cron） | on: schedule: - cron: '0 0 * * *' |
workflow_dispatch | 手動トリガー | on: workflow_dispatch: inputs: env: ... |
workflow_call | 再利用可能なワークフロー | on: workflow_call: inputs: ... |
release | リリースイベント | on: release: types: [published] |
issues | Issue イベント | on: issues: types: [opened, labeled] |
repository_dispatch | 外部イベント | on: repository_dispatch: types: [deploy] |
以下、最もよく使ういくつかを詳しく解説します。
push：最も基本的なトリガー
push は最初に出会うトリガーです。ブランチにコードがプッシュされた時にトリガーされます。
シンプルな設定：
on: pushただ、この設定には問題があります。どのブランチへのプッシュでもトリガーされます。もしリポジトリに20のブランチがあり、誰もがコードをプッシュするたびにワークフローが実行されると、無料枠はすぐになくなってしまいます。
より適切な設定は、ブランチを制限することです：
on:
push:
branches: [main, develop]またはワイルドカードを使用：
on:
push:
branches:
- 'main'
- 'release/**' # release/v1.0, release/v2.0 などにマッチpull_request：コードマージ前の守護者
pull_request は PR が作成または更新された時にトリガーされ、通常はテストの実行やコードスタイルのチェックに使われます。
on:
pull_request:
branches: [main]types フィールドでトリガーのタイミングをさらに細かく制御できます：
on:
pull_request:
types: [opened, synchronize, reopened]opened：PR が作成された時synchronize：PR に新しいコミットが追加された時reopened：PR が再度開かれた時
この設定により、この3つの場合にだけワークフローが実行され、リソースを節約できます。
schedule：定期実行タスク
schedule は Cron 式で定期実行を定義します。例えば毎日深夜にテストを実行する：
on:
schedule:
- cron: '0 0 * * *' # 毎日 UTC 0時Cron 式には5つのフィールドがあります：分、時、日、月、曜日。
よく使う時間設定：
0 0 * * *：毎日 UTC 0時（日本時間の朝8時）0 */6 * * *：6時間ごと30 2 * * 1：毎週月曜日の UTC 2:30
注意点：GitHub は UTC 時間を使用します。日本時間の朝9時にタスクを実行したい場合は、UTC 1時（0 1 * * *）に設定する必要があります。
workflow_dispatch：手動トリガー
自動トリガーではなく、ボタンをクリックして手動で実行したい場合、workflow_dispatch を使います。
on:
workflow_dispatch:
inputs:
environment:
description: 'デプロイ環境'
required: true
default: 'staging'
type: choice
options:
- staging
- production設定後、Actions ページに「Run workflow」ボタンが表示され、環境パラメータを選んでからトリガーできます。
このトリガーはデプロイシーンで特に実用的です：自動テスト、手動デプロイ。
workflow_call：再利用可能なワークフロー
ワークフローのロジックが複雑な場合、または複数のリポジトリで同じフローを使いたい場合、workflow_call でワークフローを再利用可能なコンポーネントにできます。
再利用可能なワークフローを定義：
# .github/workflows/ci.yml
on:
workflow_call:
inputs:
node-version:
required: true
type: string
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- run: npm ci && npm test別のワークフローで呼び出す：
# .github/workflows/main.yml
on: push
jobs:
call-ci:
uses: ./.github/workflows/ci.yml
with:
node-version: '20'こうすることで、異なるリポジトリ間で同じ CI ロジックを再利用でき、1箇所を変更すれば、すべての場所で反映されます。
他のトリガー（release、issues、repository_dispatch）は比較的使用頻度が低いため、詳しくは解説しません。興味があれば、GitHub 公式ドキュメントをご覧ください。
実践：最初のワークフローテンプレート
これだけ概念を説明しましたが、実際に手を動かしてみましょう。
以下は完全な Node.js プロジェクトの CI ワークフローです。そのままコピーして自分のプロジェクトで使えます：
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
# 1. コードをチェックアウト
- name: Checkout code
uses: actions/checkout@v4
# 2. Node.js 環境をセットアップ
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
# 3. 依存関係をインストール
- name: Install dependencies
run: npm ci
# 4. テストを実行
- name: Run tests
run: npm test使い方
ステップ1： プロジェクトのルートディレクトリに .github/workflows フォルダを作成します（まだない場合）。
ステップ2： そのフォルダに ci.yml ファイルを作成し、上のコードを貼り付けます。
ステップ3： コミットして GitHub にプッシュします。
プッシュした後、リポジトリの Actions タブを開くと、ワークフローが実行されているのが確認できます。
行ごとの解説
name: CI：ワークフロー名、Actions ページに表示されるon: push: branches: [main]：main ブランチにコードがプッシュされた時にトリガーon: pull_request: branches: [main]：main に対して PR が作られた時にもトリガーjobs: build:：build という名前の job を定義runs-on: ubuntu-latest：GitHub が提供する最新の Ubuntu で実行actions/checkout@v4：公式 Action、コードを仮想マシンにチェックアウトactions/setup-node@v4：公式 Action、Node.js 環境をセットアップnpm ci：依存関係をインストール（npm installより高速でクリーン）npm test：テストを実行
プロジェクトが Node.js でない場合、中間のステップを変更するだけです。例えば Python プロジェクトなら：
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install -r requirements.txt
- run: pytest基本的に「コードをチェックアウト → 環境をセットアップ → 依存関係をインストール → テストを実行」というパターンです。
よくある設定エラーのトラブルシューティング
私が踏んだ落とし穴を、皆さんには踏んでほしくありません。
問題が発生した時に確認するトラブルシューティングリストをまとめました：
| エラー現象 | 考えられる原因 | 解決策 |
|---|---|---|
| ワークフローがトリガーされない | ブランチフィルタの条件が間違っている | branches 設定を確認、ブランチ名の大文字小文字が正しいか確認 |
| YAML 解析エラー | インデントに Tab を使用 | すべてスペースに変更、YAML は Tab をサポートしない |
| Secrets が動作しない | スコープの間違い | secrets が正しいレイヤ（job または step）にあることを確認 |
| Job の依存関係が失敗 | needs の参照エラー | job-id のスペルを確認、大文字小文字を区別 |
| ワークフローが遅い | キャッシュを使っていない | actions/cache で依存関係をキャッシュ |
| 権限エラー | GITHUB_TOKEN の権限不足 | job に permissions 設定を追加 |
エラー1：インデントの間違い
これが最もよくあるエラーです、間違いなく。
YAML はインデントに極めて敏感です。スペースを使わなければならず、Tab は使えません。しかも、各レベルのインデントは2スペースでなければなりません（または他の統一された数字ですが、GitHub Actions のデフォルトは2です）。
# 間違い例：インデントが乱れている
jobs:
build:
runs-on: ubuntu-latest # この行は4スペースインデントすべき# 正しい書き方
jobs:
build:
runs-on: ubuntu-latest # 4スペースインデントほとんどのエディタ（VS Code、WebStorm）は「Tab キーでスペースを自動挿入」するように設定できます。この設定を有効にしておくことをお勧めします。毎回手動でスペースを打つ手間が省けます。
エラー2：ブランチ名の間違い
GitHub のブランチ名は大文字小文字を区別します。main と Main は別のブランチです。
# ブランチ名が main の場合
on:
push:
branches: [Main] # 間違い、トリガーされない
# 正しい書き方
on:
push:
branches: [main] # 小文字ブランチ名がわからない場合は、GitHub リポジトリページで確認するか、ローカルで git branch を実行してください。
エラー3：job-id のスペルミス
ワークフローに複数の job があり、依存関係がある場合、needs フィールドは他の job の id を正確に参照する必要があります。
jobs:
test:
runs-on: ubuntu-latest
# ...
deploy:
needs: Test # 間違い、大文字小文字が一致しない
runs-on: ubuntu-latest# 正しい書き方
jobs:
test:
runs-on: ubuntu-latest
deploy:
needs: test # 小文字、上の job id と一致
runs-on: ubuntu-latestエラー4：Secrets のレイヤ間違い
GitHub の Secrets には2つのスコープがあります：リポジトリレベルと環境レベル。参照する時は ${{ secrets.XXX }} を使用します。
# 間違い例：secrets の書き方が間違っている
jobs:
build:
runs-on: ubuntu-latest
env:
API_KEY: secrets.MY_KEY # 間違い、${{ }} がない# 正しい書き方
jobs:
build:
runs-on: ubuntu-latest
env:
API_KEY: ${{ secrets.MY_KEY }} # ${{ }} で囲むまた、Secrets は暗号化されているため、ログでは実際の値を見ることができません。値が正しく渡されたかをログで確認したい場合、代替値を出力できます：
- name: Debug
run: echo "API_KEY is set: ${{ secrets.MY_KEY != '' }}"これで実際の Key は漏洩しませんが、空でないかどうかは確認できます。
FAQ
GitHub Actions ワークフローに必須のフィールドは？
push と pull_request トリガーの違いは？
YAML のインデントは Tab とスペースのどちら？
無料枠はどれくらい？超えたらどうなる？
GitHub Actions と他の CI/CD ツールの比較
Jenkins、GitLab CI、CircleCI を使ったことがあるかもしれません。GitHub Actions はそれらと比べてどうなのでしょうか？
比較表をまとめました：
| 比較項目 | GitHub Actions | GitLab CI | Jenkins | CircleCI |
|---|---|---|---|---|
| 設定言語 | YAML | YAML | Groovy | YAML |
| ホスティング方式 | クラウドネイティブ | クラウド/セルフホスト | セルフホスト | クラウドネイティブ |
| 統合度 | GitHub ネイティブ | GitLab ネイティブ | 設定が必要 | 設定が必要 |
| 学習曲線 | 低い | 低い | 高い | 中程度 |
| 料枠 | 2000分/月（プライベート） | 400分/月 | 無制限（セルフホスト） | 6000分/月 |
| パブリックリポジトリ | 無制限 | 無制限 | 制限 | 無制限 |
GitHub Actions の利点
1. ゼロ設定での統合
コードが既に GitHub でホストされている場合、GitHub Actions は最も自然な選択です。Webhook を追加設定する必要も、サーバーを維持する必要も、プラグインをインストールする必要もありません。YAML ファイルを作成してプッシュすれば、すぐに実行できます。
2. Marketplace のエコシステム
GitHub Marketplace には何千もの Actions があり、AWS、Azure、Google Cloud すべてが公式 Actions を提供しています。必要な機能は、おそらく誰かが既に作成しています。uses で直接呼び出すだけです。
3. 個人開発者に優しい無料枠
パブリックリポジトリは無制限に使用でき、プライベートリポジトリは月2000分です。個人プロジェクトや小規模チームには十分です。
GitHub Actions を選ばない方がいい場合
1. コードが GitHub にない場合
GitLab や Bitbucket を使用している場合、それぞれの CI/CD を使うべきです。GitHub Actions は Webhook でトリガーできますが、わざわざ回り道をするより、ネイティブのソリューションを使う方が良いでしょう。
2. 実行環境を完全に制御する必要がある場合
GitHub Actions の runner 環境は固定されています（Ubuntu/Windows/macOS）。独自のソフトウェアをインストールしたり、特別な環境を構築したりすることはできません。この場合、Jenkins + セルフホスト runner の方が柔軟です。
3. セキュリティに極端な要件がある場合
GitHub Actions の runner は GitHub がホストする仮想マシンです。コードが極めて機密性の高い情報を含む場合、独自の CI システムを構築する必要があるかもしれません。ただし、GitHub も self-hosted runner をサポートしているので、折衷案として使えます。
私のアドバイス
ほとんどの個人開発者と小規模チームにとって：
- コードが GitHub → GitHub Actions を選択
- コードが GitLab → GitLab CI を選択
- 高度なカスタマイズが必要 → Jenkins または self-hosted runner
絶対的な正解はありません。自分に合ったものがベストです。
まとめ
ここまで読んで、GitHub Actions の YAML ワークフローについて大体理解できたと思います。
重要なポイント：
- 4つのコアフィールド：
name（命名）、on（トリガー）、jobs（タスク定義）、steps（実行ステップ） - 8種類のよく使うトリガー：最もよく使うのは
push、pull_request、schedule - コピー可能なテンプレート：コードチェックアウト → 环境セットアップ → 依存関係インストール → テスト実行
- 4つのよくある落とし穴：インデント、ブランチ名、job-id、Secrets
次のステップ：
- 自分のプロジェクトで最初のワークフローを作成（この記事のテンプレートをコピーして、プロジェクトの設定に変更するだけ）
- シリーズの上級記事「GitHub Actions キャッシュ戦略：CI/CD パイプラインを5倍高速化」を読んで、ワークフローをより速くする方法を学ぶ
- GitHub Marketplace を覗いてみて、直接使える便利な Actions を探す
自動化、一度その甘さを味わったら、もう元には戻れません。
6 min read · 公開日: 2026年4月10日 · 更新日: 2026年4月11日
関連記事
Nginx パフォーマンスチューニング：gzip、キャッシュ、接続プール設定
Nginx パフォーマンスチューニング：gzip、キャッシュ、接続プール設定
GitHub Actions 入門：YAML ワークフローの基礎とトリガー設定
GitHub Actions 入門：YAML ワークフローの基礎とトリガー設定
n8n 実践ガイド：Webhook トリガーと IF/Switch 条件分岐の設計
コメント
GitHubアカウントでログインしてコメントできます