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

.github/workflowsフォルダの中のYAMLファイルを初めて見たとき、私は少し戸惑いました。インデント、コロン、そしてよく分からないキーワードの数々——on、jobs、runs-on。これは何だ？食べられるのか？

その後プロジェクトが増えていき、コードをプッシュするたびに手動でテストを走らせ、手動でデプロイする。何度かやっているうちに面倒になってきました。そこでようやく気づいたのです。GitHub Actionsというもの、本当にかなりの手間を省いてくれる、と。

この記事では、GitHub Actionsの基礎——YAMLワークフローの書き方、トリガーの設定方法について話したいと思います。派手な高度な機能は扱いません。最も実用的で、最もよく使う部分だけを取り上げます。読み終えたら手を動かせる、それが肝心です。

GitHub Actionsは何をしてくれるのか

ひとことで言えば、自動化です。

以前はコードをプッシュした後、手動でいろいろやる必要がありました。テストを走らせ、コードのフォーマットをチェックし、プロジェクトをビルドし、サーバーにデプロイする。今ではこれらの手順をYAMLファイルに書いておけば、GitHubが自動で実行してくれます。

例を挙げましょう。コードをmainブランチにプッシュするたびに、GitHub Actionsが自動でテストを走らせる。テストが通って初めてPRのマージが許可される。こうすればコード品質が担保され、自分も楽になります。

もう一つの利点：無料です。パブリックリポジトリは完全に無料、プライベートリポジトリも毎月2000分の無料枠があります（個人プロジェクトには十分すぎるほど）。

YAMLワークフローはどんな見た目か

まずは一番シンプルな例を見てみましょう：

name: テストワークフロー

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: あいさつを出力
        run: echo "Hello, GitHub Actions!"

一行ずつ分解します：

name：ワークフローの名前。自由につけてよく、GitHub Actionsのページで識別しやすくするためのものです。

on：トリガー条件。ここではpushと書いており、コードをプッシュするたびにこのワークフローが起動するという意味です。

jobs：タスクのブロック。1つのワークフローは複数のjob（タスク）を含むことができ、並列または直列で実行できます。

build：このjobのID。自由に命名できますが、意味のある名前を推奨します（例：build、test、deploy）。

runs-on：実行環境。ubuntu-latestは最新のUbuntuサーバー上で走ることを表します。windows-latest、macos-latestも選べます。

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

steps：手順のリスト。1つのjobは複数のstepから成り、順番に実行されます。

run：実行するコマンド。ここではひとこと出力するだけです。

これが最も基本的な骨格です。後に出てくる複雑なワークフローも、結局はこの基礎の上にjobやstep、判定ロジックを積み重ねていくだけ。でも慌てないでください。まず基礎を理解すれば、複雑なものは自然と分かるようになります。

トリガー：いつ走るかをワークフローに教える

トリガー（trigger）はワークフロー全体の「スイッチ」です。正しく設定して初めて、ワークフローは適切なタイミングで走り出します。

よく使うトリガーは4種類：push、pull_request、schedule、workflow_dispatch。一つずつ見ていきましょう。

1. push：コードをプッシュしたときに起動

最もよく使うトリガーです。

on: push

こう書くと、どのブランチにコードをプッシュしても起動します。

ただ通常は、特定のブランジだけで起動させたいものです：

on:
  push:
    branches:
      - main
      - dev

この設定の意味：mainまたはdevブランチにプッシュしたときだけ起動する。他のブランチは？対象外です。

さらに細かく——特定のパスの変更だけを監視することもできます：

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
      - 'package.json'

src/ディレクトリ下のファイルかpackage.jsonが変わったときだけ起動します。こうすればドキュメントや設定ファイルを変更したときに、無駄にCIを一回走らせずに済みます。

2. pull_request：PR関連の操作で起動

PR（Pull Request）はチーム協働の中心的なシーンです。

on: pull_request

こう書くと、PRのすべての操作で起動します。PRを開く、PRを更新する、PRを再オープンする。

ただ同様にブランチを限定できます：

on:
  pull_request:
    branches:
      - main

対象ブランチがmainのPRだけで起動します。

PRの操作タイプを指定することもできます：

on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened

• opened：PRが開かれたとき
• synchronize：PRに新しいコミットがあったとき（例：新しい変更をプッシュした）
• reopened：閉じたPRが再オープンされたとき

この設定はかなりよく見かけます——PRが開かれたときにテストを走らせ、変更に問題がないことを確認するのです。

3. schedule：定期実行で起動

定時タスクのように、計画に沿ってワークフローを走らせます。

on:
  schedule:
    - cron: '0 0 * * *'

これはcron式で、書式は分 時 日 月 曜日です。

上の行の意味は、毎日UTC時間0時（日本時間の午前9時）に一回走る、です。

よくあるシーン：毎日自動でテストを走らせる、定期的にキャッシュをクリアする、定時にレポートを生成する。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

正直なところ、cron式はかなり書き間違えやすいです。検証を手伝ってくれるオンラインツールがいくつかあります、例えばcrontab.guruなど。

4. workflow_dispatch：手動で起動

手動で起動したいときもあります——例えばワンクリックデプロイ、特定のタスクを手動で走らせる、など。

on: workflow_dispatch

設定すると、GitHub Actionsのページに「Run workflow」ボタンが現れます。クリックすれば手動で起動できます。

入力パラメータを設定することもできます：

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'デプロイ環境'
        required: true
        default: 'production'
        type: choice
        options:
          - production
          - staging

手動起動時にどの環境へデプロイするかを選べます。これでテスト環境にも本番環境にもワンクリックでデプロイできます。便利でしょう？

トリガーの組み合わせ

実際のプロジェクトでは、複数のトリガーが必要になることがよくあります：

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  schedule:
    - cron: '0 6 * * 1'  # 毎週月曜の朝6時 UTC
  workflow_dispatch:

この設定の意味：

• mainブランチにプッシュしたときに起動
• 対象ブランチがmainのPRで起動
• 毎週月曜の朝に一回走る
• 手動起動にも対応

1つのワークフローで、複数の起動方法。よく見かける設定パターンです。

実践：Node.jsプロジェクトに自動テストを設定する

実用的な例を書いてみましょう——Node.jsプロジェクトで自動的にテストを走らせます。

あなたのプロジェクト構成がこうだとします：

my-project/
├── src/
├── tests/
├── package.json
└── .github/
    └── workflows/
        └── test.yml

.github/workflows/test.ymlファイルを作成します：

name: 自動テスト

on:
  push:
    branches:
      - main
      - dev
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      # 1. コードをチェックアウト
      - name: コードのチェックアウト
        uses: actions/checkout@v4

      # 2. Node.jsをインストール
      - name: Node.jsのセットアップ
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      # 3. 依存関係をインストール
      - name: 依存関係のインストール
        run: npm ci

      # 4. テストを実行
      - name: テストの実行
        run: npm test

      # 5. コードフォーマットチェック（任意）
      - name: コードフォーマットのチェック
        run: npm run lint

各手順を一つずつ説明します：

コードのチェックアウト：actions/checkout@v4は公式が提供するActionで、あなたのコードリポジトリを実行環境にダウンロードします。

Node.jsの設定：actions/setup-node@v4も公式Actionで、指定したバージョンのNode.jsをインストールします。node-version: '20'はNode.js 20を使うことを表します。

依存関係のインストール：npm ciはnpm installよりCI環境に向いています——package-lock.jsonに厳密に従ってインストールするので、より速く信頼性が高いです。

テストの実行：あなたのテストコマンドをそのまま走らせます。前提としてpackage.jsonにtestスクリプトが設定されていることが必要です。

コードフォーマットチェック：ESLintやPrettierを設定していれば、このステップでコードフォーマットを自動チェックできます。

このワークフローはmainまたはdevブランチにプッシュしたときに起動し、対象ブランチがmainのPRでも起動します。こうすれば変更のたびにテストが番人として機能します。

よくある落とし穴

正直なところ、私も書き始めた頃はYAMLでかなりの落とし穴にはまりました。ここでよくあるものをいくつか挙げます：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

1. インデントの誤り

YAMLはインデントに極めて敏感です。必ず半角スペースを使い、Tabは使えません。インデントの階層は一貫している必要があります。

# ❌ 誤り：インデントが不一致
jobs:
build:
  runs-on: ubuntu-latest

# ✅ 正しい：インデントを統一
jobs:
  build:
    runs-on: ubuntu-latest

エディタのYAMLプラグインを使うのを推奨します。インデントの誤りを自動でハイライトしてくれます。

2. トリガーが効かない

トリガーを設定したのにワークフローが走らないことがあります。よくある原因：

• ブランチ設定の誤り：例えばdevelopブランチにプッシュしたが、設定ではmainしか監視していない
• forkしたリポジトリ：forkリポジトリからのプッシュはpushイベントのワークフローを起動しない
• forkからのPR：forkから来たPRはデフォルトで一部のトリガーを起動しない

3. コードのチェックアウトを忘れる

初心者が最も犯しやすいミス：actions/checkout@v4を使うのを忘れることです。

このステップがないと、ワークフロー環境は空っぽです——あなたのコードがそこに存在しません。

steps:
  # ❌ 誤り：コードをチェックアウトせずにコマンドを実行
  - run: npm test

  # ✅ 正しい：先にコードをチェックアウト
  - uses: actions/checkout@v4
  - run: npm test

4. Actionのバージョンが古すぎる

一部のチュートリアルではactions/checkout@v2やv3が使われています。ですが最新版のv4を推奨します。機能がより充実し、パフォーマンスも良いです。

使っているActionに新しいバージョンがないか定期的にチェックしましょう。GitHubがバージョンの古さを知らせてくれます。

いくつかの実用的なアドバイス

トリガー選択の原則

自分にいくつか問いかけてみましょう：

• 自動で走らせたいか、手動で走らせたいか？ → 自動ならpush/pull_request、手動ならworkflow_dispatch
• 走る頻度は高いか？ → 頻度が高いならブランチやパスを限定し、リソースの浪費を避ける
• チームで協働するか？ → PRのシーンにはpull_requestが必須

パフォーマンス最適化の小技

• 起動範囲を限定する：重要なブランチとパスだけを監視する
• 並列実行：独立した複数のjobは並列で走らせられる
• キャッシュの活用：actions/setup-nodeはNode.jsと依存関係を自動でキャッシュするので、毎回入れ直す必要がない

命名は明確に

# ❌ 曖昧な命名
jobs:
  job1:
    steps:
      - name: step1

# ✅ 明確な命名
jobs:
  test:
    steps:
      - name: 依存関係のインストール

明確な名前は問題の切り分けに役立ちます——GitHub Actionsのページは各stepの名前を表示します。

おすすめの学習ルート

この記事では基礎だけを扱いました。さらに深く学びたいなら、続けて学べる項目があります：

1. マトリックスビルド：複数の環境（Node.js 16、18、20）で同時にテストを走らせる
2. キャッシュ最適化：手動でキャッシュを設定し、ビルド速度を上げる
3. Secret管理：APIキーやパスワードなどの機密情報を安全に保存する
4. カスタムAction：自分のActionにまとめて、ロジックを再利用する
5. デプロイの自動化：サーバーやクラウドプラットフォームへ自動でデプロイする

公式ドキュメントが最良のリソースです：GitHub Actionsドキュメント。内容はとても充実していますが、ちょっと長めです。

もう一つアドバイス：他人の設定をたくさん見ること。GitHub上の多くのオープンソースプロジェクトの.github/workflowsフォルダには完全な設定があります。そのまま真似してもOKです。

最後にひとこと

いろいろ話しましたが、要するに核心は3つだけです：

1. YAMLの構造：name、on、jobs、stepsの4つのキーワードで骨格を組む
2. トリガーの設定：push、pull_request、schedule、workflow_dispatchの4つが最もよく使う
3. 実践例：Node.jsの自動テストは最も典型的な入門シーン

最初のワークフローを書き上げた後のあの感覚を、私は今でも覚えています——コードをプッシュすると、GitHubが自動でテストを走らせ、そして「テストが通りました」とメールで知らせてくれる。あの「すべてが手の中にある」という安心感は、本当になかなか爽快でした。

この後さらに高度な機能（マトリックスビルド、キャッシュ最適化、デプロイの自動化）を学びたくても、基礎をしっかり固めておけば難しくありません。GitHub Actionsというもの、入門のハードルは高くありませんが、使いこなせれば本当にかなりの時間を節約できます。少なくとも、コードをプッシュするたびに手動でテストを走らせる必要はもうなくなる。そうでしょう？

参考資料

• GitHub Actions公式ドキュメント
• Workflow Syntax for GitHub Actions
• Events that trigger workflows
• 阮一峰 GitHub Actions入門チュートリアル