GitHub Actions 入門：YAML ワークフローの基礎とトリガー設定

画面に出た赤いエラーが目に刺さって、キーボードを叩き割りたくなる。

ローカルではちゃんと動いていたコードが、GitHub に push した途端に落ちる。あの YAML ファイルはもう 6 回も直したのに、毎回インデントの問題だ。これ、コードを書くより難しくないか？

実のところ、GitHub Actions そのものは複雑ではありません。難しいのはドキュメントのほう。いきなり数百ページの設定説明を投げつけられて、読むだけで頭がくらくらします。この記事では、いちばんシンプルなやり方で、YAML ワークフローのコア構造を理解していきましょう。

この記事で学べること：

• YAML ファイルの 4 大コア要素と、それぞれの実際の役割
• よく使う 8 種類のトリガーの設定方法と使いどころ
• そのままコピーして使える完全なワークフローテンプレート
• 筆者がハマった落とし穴と、その回避方法

準備はいいですか。さっそく始めましょう。

YAML ワークフローファイル：4 大コア要素

正直に言うと、GitHub Actions を触り始めたころ、.github/workflows ディレクトリの YAML ファイルを見て、まるで暗号を読んでいる気分でした。インデントだらけ、コロンだらけ、スペースを 1 つ間違えただけで全部落ちる。

でも後で気づいたんです。これ、要するにコアは 4 つだけなんだと。この 4 つを押さえれば、あとは応用にすぎません。

name：ワークフローに名前をつける

この要素がいちばんシンプルですが、多くの人（筆者も含めて）が最初は見落とします。

name: CI for Node.js App

name は、GitHub Actions のタブに表示されるワークフローの名前です。コードを push したあと、リポジトリの Actions ページを開くと出てくる、あの行のことです。

名前のつけ方にはちょっとしたコツがあります。プロジェクト名 + 機能の説明を使うこと。たとえば MyApp CI、Backend Deploy のように。こうしておくと、ワークフローが増えても、見たいものを一目で見つけられます。

この要素は実は省略できます。書かなければ、GitHub がファイル名で代用します。ただ、省略はおすすめしません。ファイル名はたいてい英語の略称で、ぱっと見では直感的ではないからです。

on：いつトリガーするか

on はワークフロー全体の「スイッチ」です。どんなときにこのワークフローを動かすかを、GitHub に伝えます。

いちばんシンプルな書き方：

on: push

意味は「コードが push されたら必ずトリガーする」です。

ただ実際のプロジェクトでは、もっと細かい制御が必要になります。たとえば main ブランチに push があったときだけ動かす：

on:
  push:
    branches: [main]

あるいは Pull Request の作成時にもトリガーしたい場合：

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

トリガーは GitHub Actions の真髄です。後ほど 1 節まるごと使って、よく使う 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 を 1 つずつ順番に実行します。

各 step には 2 つの書き方があります。

1. run でコマンドを実行する：

steps:
  - name: Install dependencies
    run: npm ci

  - name: Run tests
    run: npm test

run のあとに続くのは、ターミナルで実行したいコマンドそのものです。ローカルでコマンドを打つのとまったく同じです。

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' は、setup-node に「Node.js 20 を使いたい」と伝えています。

4 つの要素の説明は以上です。思ったよりシンプルではないですか。

トリガー徹底解説：よく使う 8 つのシーン

先ほど on 要素がトリガーのタイミングを決めると述べました。GitHub Actions は数十種類のトリガーに対応していますが、正直よく使うのはごく一部です。

表にまとめたので、各トリガーの使いどころをすばやく把握してください：

トリガー	典型的なシーン	設定例
push	コードをブランチに 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 は、最初に出会うトリガーです。コードをブランチに push したときにトリガーされます。

シンプルな設定：

on: push

ただ、この設定には問題があります。どのブランチへの push でもトリガーされてしまうのです。リポジトリに 20 個のブランチがあって、みんなが push するたびにワークフローが動けば、無料枠はあっという間に使い切ってしまいます。

より合理的なのは、ブランチを限定する設定です：

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 式で定期トリガーを定義します。たとえば毎日深夜にテストを 1 回走らせる：

on:
  schedule:
    - cron: '0 0 * * *'  # 毎日 UTC 0 時

Cron 式には 5 つのフィールドがあります。分、時、日、月、曜日です。

よく使う時刻をいくつか：

• 0 0 * * *：毎日 UTC 0 時（日本時間の午前 9 時）
• 0 */6 * * *：6 時間ごと
• 30 2 * * 1：毎週月曜の UTC 2:30

注意したい落とし穴があります。GitHub は UTC 時間を使います。日本時間の午前 9 時にタスクを動かしたいなら、UTC 0 時（0 0 * * *）に設定する必要があります。

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 に push します。

push したあと、リポジトリの Actions タブを開けば、ワークフローが動いているのが見えるはずです。

1 行ずつ解説

• name: CI：ワークフロー名。Actions ページに表示される
• on: push: branches: [main]：main ブランチへの push でトリガー
• 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 != '' }}"

これなら実際のキーを漏らさずに、空かどうかを確認できます。

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 ファイルを 1 つ作って push すれば、すぐに動きます。

2. Marketplace のエコシステム

GitHub Marketplace には数千もの Action があり、AWS、Azure、Google Cloud にも公式 Action があります。必要な機能は、たいてい誰かがすでに作ってくれているので、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

このあとは、こんなことに取り組めます：

1. 自分のプロジェクトで最初のワークフローを作る（この記事のテンプレートをコピーし、自分のプロジェクト設定に変えるだけ）
2. シリーズの応用記事『GitHub Actions のキャッシュ戦略：CI/CD パイプラインを 5 倍速くする』を読み、ワークフローをもっと速く動かす方法を知る
3. GitHub Marketplace をのぞいて、そのまま使える便利な Action を探す

自動化というのは、一度その味を覚えると、もう後戻りできなくなります。