GitHub Actions CI パイプライン実践：自動ビルド・テストをゼロから構築

スマホが震える。同僚からのメッセージ。「本番環境が落ちた。昨日マージした君のコードに問題があるみたい」。

頭が真っ白になる。ローカルではちゃんとテストが通ったのに。あとでログを見て分かったのは、ローカルの Node バージョンは 20、テスト環境は 18 で、ある API の挙動が一致せずバグになっていたということだった。その瞬間、こう思った。マージ前に自動でテストを一度走らせる CI パイプラインがあれば、こんなことは起きなかったのに、と。

テストを手動で走らせること自体、10 人の開発者のうち 9 人は忘れる。忘れないもう 1 人は、たいてい一度痛い目に遭っている。GitHub Actions はまさにこの問題を解決するためにあります。コードを push したら自動でビルド・テスト・デプロイ。気にしなくても、マシンが代わりにやってくれます。

この記事では、完全な CI パイプラインをゼロから構築していきます。内容は、そのままコピーして使えるワークフローのテンプレート、Matrix 戦略による複数バージョンの並列テスト（ビルド時間を半分以上削減できます）、そして踏んだ落とし穴と実践的な経験です。準備はいいですか。始めましょう。

第1章：GitHub Actions クイックスタート

GitHub Actions とは

簡単に言えば、GitHub Actions は GitHub に組み込まれた自動化プラットフォームです。ローカルでコードを push すると、クラウド側でテスト・ビルド・デプロイを代わりにやってくれます。すべて自動です。

以前は CI/CD をやるために、自分で Jenkins サーバーを立て、設定・保守・アップグレードまですべて手作業でした。GitHub Actions のすごいところは、サーバーを管理する必要も、ソフトをインストールする必要もなく、リポジトリに YAML ファイルを 1 つ置けば終わる点です。しかも毎月 2000 分が無料で付与されます（パブリックリポジトリは無制限）。個人プロジェクトや小規模チームには十分すぎる量です。

Jenkins や Travis CI と比べると、GitHub Actions の利点はかなり明確です。GitHub リポジトリと深く統合されていて、PR 内で直接ビルド状態を確認できます。設定がシンプルで、Groovy の文法を学ぶ必要もありません。エコシステムも豊富で、公式の Marketplace に何万もの既製 Action があり、すぐに使えます。欠点もあります。GitHub に縛られるため、GitLab へ移行したくなったら設定を書き直す必要があります。複雑なエンタープライズ級のパイプラインなら、Jenkins のほうが柔軟かもしれません。とはいえ、ほとんどのプロジェクトには GitHub Actions で十分です。

主要な概念をざっくり把握

GitHub Actions を学び始めると、いくつかの概念で混乱しがちです。かみ砕いて説明します。

Workflow（ワークフロー）：1 つの YAML ファイルで、一連の自動化フローを定義します。たとえば「main ブランチに push するたびにテストを走らせる」、これが 1 つのワークフローです。.github/workflows/ ディレクトリに置きます。

Job（ジョブ）：ワークフロー内の一連のステップのまとまりです。複数の Job は並列実行も、依存関係の設定もできます。たとえば先に「テスト」Job を走らせ、その後「デプロイ」Job を走らせる、といった具合です。

Step（ステップ）：Job 内の具体的な操作で、順番に 1 つずつ実行されます。1 行のコマンド実行（npm test）でも、他人が作った Action の呼び出し（actions/checkout@v4）でも構いません。

Runner（ランナー）：Job を実行する仮想マシンです。GitHub は 3 種類を提供しています。ubuntu-latest（Linux）、windows-latest（Windows）、macos-latest（macOS）です。自分のサーバーを使うこともできますが、多くの場合は公式のもので十分です。

たとえるなら、Workflow は台本、Job は台本の中のいくつかの場面、Step はその場面ごとの具体的な動作、Runner はその場面を演じる役者です。

あなたの最初の CI ワークフロー

あれこれ考えすぎず、まずは動かしてみましょう。プロジェクトのルートに .github/workflows/ci.yml を作成し、以下のコードを貼り付けてください。

name: CI Pipeline  # ワークフロー名。GitHub Actions ページに表示される

on:
  push:
    branches: [main]  # main ブランチに push したときにトリガー
  pull_request:
    branches: [main]  # main 向けの PR のときにトリガー

permissions:
  contents: read  # 最小権限の原則：読み取り権限だけを付与

jobs:
  build:
    runs-on: ubuntu-latest  # 最新の Ubuntu 環境を使用
    timeout-minutes: 15     # タイムアウト時間。ハングを防ぐ

    steps:
      - name: Checkout code
        uses: actions/checkout@v4  # コードを取得

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20   # Node.js 20 を使用
          cache: 'npm'        # npm キャッシュを有効化

      - name: Install dependencies
        run: npm ci          # 依存関係をインストール。ci は install より速く確実

      - name: Run tests
        run: npm test        # テストを実行

      - name: Build
        run: npm run build   # ビルド

このコードは何をしているのでしょうか。

最初の部分 on はトリガー条件を定義します。main ブランチへの push、または main 向けの PR のときにトリガーします。2 番目の部分 permissions は権限を宣言し、最小権限の原則に従って contents: read だけを付与し、ワークフローが誤ってリポジトリを変更するのを防ぎます。3 番目の部分が中心です。build という Job が Ubuntu 上で走り、コード取得、Node のセットアップ、依存インストール、テスト、ビルドの各ステップを順に実行します。

このコードをコミットして GitHub に push し、リポジトリの Actions ページを開いてください。緑色の小さな丸が回っているのが見えます。これは Runner があなたのワークフローを実行している印です。数分待ち、すべて緑色のチェックになれば、おめでとうございます。最初の CI パイプラインが通りました。

赤いバツが出たらどうするか。クリックして中に入ればログが見えます。各ステップの出力がはっきり表示されます。90% は依存インストールの失敗かテスト自体の問題で、CI 設定とはあまり関係ありません。

第2章：CI パイプラインの主要設定

第1章のワークフローは動きますが、本当に使えるレベルにはまだ距離があります。この章では、4 つの主要設定について話します。トリガー、権限管理、環境変数、依存キャッシュです。これらは CI パイプラインの骨組みで、適切に設定すればワークフローをより安全で効率的にできます。

トリガー：いつ実行するか

トリガーはワークフローをいつ起動するかを決めます。最もよく使う 2 つは push と pull_request です。

on:
  push:
    branches: [main, dev]    # main または dev ブランチへの push でトリガー
    paths:
      - 'src/**'             # src ディレクトリ配下のファイル変更のときだけトリガー
      - 'package.json'       # package.json の変更でもトリガー（依存更新）
  pull_request:
    branches: [main]         # main 向けの PR でトリガー

paths フィルターは特に実用的です。たとえばプロジェクトにドキュメントディレクトリ docs/ があるとして、ドキュメントの変更で CI をトリガーすべきではありません。paths 設定を加えれば、コードの変更時だけビルドが走り、リソースも時間も節約できます。

push と PR 以外にも、いくつかのトリガー方法があります。

schedule：定期実行で、cron 式を使います。たとえば毎日深夜にビルドを 1 回走らせる場合：

on:
  schedule:
    - cron: '0 0 * * *'  # 毎日 UTC 0 時（日本時間 9 時）

私はあるプロジェクトでこれを定期的な依存チェックに使っています。毎日 npm outdated を走らせ、古くなったパッケージを検出して自動でメール通知します。

workflow_dispatch：手動トリガーです。コードを push せずにビルドを 1 回走らせたいとき（たとえばある設定をテストするとき）に役立ちます。Actions ページに「Run workflow」ボタンが表示され、クリックすれば手動で実行できます。

on:
  workflow_dispatch:  # 手動トリガー。追加設定は不要

権限管理：セキュリティ第一

GitHub Actions はデフォルトでワークフローに GITHUB_TOKEN を渡します。この token はリポジトリの読み書き、PR の作成、さらにはコードの push までできます。便利そうに聞こえますが、リスクでもあります。ワークフローが悪用されれば、攻撃者がリポジトリの書き込み権限を得られてしまいます。

2021 年にあるセキュリティ事件があり、あるオープンソースプロジェクトの CI ワークフローが悪用され、攻撃者が偽装した PR を通じて悪意あるコードを送り込みました。痛ましい教訓です。そのため現在、GitHub はある原則を推奨しています。最小権限を明示的に宣言することです。

permissions:
  contents: read    # リポジトリ内容の読み取りのみ。書き込み不可
  pull-requests: write  # PR を作成する必要があれば、個別に宣言する

純粋な CI パイプライン（テストとビルドだけ）なら、contents: read で十分です。ワークフローで Release の公開や PR へのコメントなどが必要なら、必要に応じて権限を追加します。

実用的なテクニックを 1 つ。リポジトリ設定でデフォルト権限を「Read repository contents permission」に変えておくと、すべてのワークフローがデフォルトで読み取り権限だけになり、書き込みが必要なものは個別に宣言する形になります。防御線が 1 つ増え、リスクが 1 つ減ります。

環境変数：階層管理

環境変数には 3 つの階層があります。workflow レベル、job レベル、step レベルです。レベルが低いほど作用範囲は狭くなりますが、上位レベルの値を上書きできます。

env:
  NODE_ENV: production     # workflow レベル。すべての job で使える
  CI: true                 # 多くのツールはこの変数を検出すると挙動を調整する

jobs:
  build:
    env:
      BUILD_TARGET: web    # job レベル。build job 内だけで有効

    steps:
      - name: Run custom script
        env:
          MY_VAR: hello    # step レベル。このステップだけで有効
        run: echo $MY_VAR

なぜ階層化するのか。例を挙げます。プロジェクトに複数の Job、build と deploy があるとします。NODE_ENV は両方の Job で必要なので workflow レベルに置きます。一方 BUILD_TARGET は build Job だけで使うので、job レベルに置くほうが分かりやすいです。あるステップで一時的な変数が必要なら（あるスクリプトの引数など）、step レベルに置きます。

機密情報はどう扱うか。絶対に YAML に直接書かないでください。GitHub は Secrets 機能を提供しています。リポジトリ設定で鍵（たとえば API_KEY）を追加し、ワークフロー内で ${{ secrets.API_KEY }} として参照します。Secrets はログ内で自動的に伏せられ、漏洩しません。

steps:
  - name: Deploy to server
    env:
      SSH_KEY: ${{ secrets.SSH_KEY }}  # Secrets から参照
    run: |
      echo "$SSH_KEY" > private.key
      ssh -i private.key user@server 'deploy.sh'

依存キャッシュ：ビルドを高速化

プロジェクトの依存関係が多い場合（数百個の npm パッケージ）、毎回 CI で一から入れていると時間がかかります。私のあるプロジェクトでは、依存インストールに 3 分、テストに 1 分かかり、依存インストールが時間の 75% を占めていました。

GitHub Actions はキャッシュの仕組みを提供しており、インストール済みの依存関係を保存して次回はそのまま使えます。最も簡単な方法は、setup-node 内蔵のキャッシュです。

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'  # npm 依存関係を自動キャッシュ

cache: 'npm' を 1 行加えると、初回は通常どおりインストールし、同時に node_modules をキャッシュに保存します。2 回目以降は、package-lock.json が変わっていなければキャッシュから直接取得し、インストール時間が 3 分から 10 秒になります。

pnpm や yarn を使うなら、cache: 'pnpm' または cache: 'yarn' に変えます。

より細かいキャッシュには actions/cache を使えます。

- name: Cache dependencies
  uses: actions/cache@v4
  with:
    path: ~/.npm         # npm のグローバルキャッシュディレクトリ
    key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

key はキャッシュの一意な識別子です。ここでは package-lock.json のハッシュ値を使っています。ロックファイルが変わればキャッシュは無効になり、再インストールされます。restore-keys は予備の戦略です。完全一致が見つからない場合、同種のキャッシュを探して一部だけ先に復元します。

キャッシュのヒット率が高ければ、ビルド速度はかなり速くなります。私のあるプロジェクトの実測では、キャッシュ無しで 4 分、キャッシュ有りで 1.5 分でした。毎日 20 回ビルドを走らせれば、節約できる時間でブログを 1 本書けます。

第3章：Matrix 戦略：並列テスト

これは私が最も気に入っている GitHub Actions の機能であり、この記事の核となる売りでもあります。Matrix 戦略は 1 つの Job を複数の並列実行する Job に変え、異なるバージョンや異なる OS を同時にテストできます。一度の push で、数秒のうちに十数個のビルドタスクを起動し、すべて並列で走らせるので、総時間は直列実行の半分以下になります。

Matrix とは

たとえるなら、プロジェクトが Node 16、18、20 の 3 バージョンで正常に動くかをテストしたいとします。従来のやり方は、3 つの Job を書くか、1 つの Job 内で順番にバージョンを切り替えてテストするかです。これだと設定が冗長になるか、時間が長くなるかのどちらかです。

Matrix は表のようなものです。横軸が Node バージョン、縦軸が OS で、各マスが独立したテストタスクになります。GitHub Actions はすべての組み合わせを自動生成し、並列実行します。

strategy:
  matrix:
    node: [16, 18, 20]
    os: [ubuntu-latest, windows-latest]

この設定は 6 つの Job を生成します。Ubuntu 上の Node 16、Windows 上の Node 16、Ubuntu 上の Node 18……というように続きます。すべて完了するまでの総時間は、最も遅い 1 つの Job に依存し、すべての Job の合計ではありません。

バージョンマトリクス：複数 Node バージョンのテスト

私はあるプロジェクトでこんな問題に遭遇しました。開発には Node 20 を使っていたのですが、ある日ユーザーから Node 18 で動かないと報告がありました。調べてみると、ある API が Node 18 で挙動が違っていたのです。もっと早く複数バージョンのテストをしていれば、このバグは外に出ることはありませんでした。

Matrix で複数バージョンのテストをするのはとても簡単です。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false    # あるバージョンが失敗しても他のバージョンは続行
      matrix:
        node-version: [16, 18, 20, 22]  # この 4 バージョンをテスト

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}  # matrix のバージョンを動的に使用
          cache: 'npm'
      - run: npm ci
      - run: npm test

主要なポイントを説明します。

• matrix.node-version はテストするバージョンのリストを定義します
• ${{ matrix.node-version }} を steps 内で参照すると、各 Job が異なる値を受け取ります
• fail-fast: false は、あるバージョンが失敗しても他のバージョンを中断せず続行する設定です。デフォルトは true で、1 つ失敗すると全部止まります。互換性テストのときはオフにするのがおすすめで、こうするとすべてのバージョンのテスト結果が見られます。

include と exclude：ある組み合わせをテストする必要がなかったり、追加設定が必要だったりする場合は、この 2 つのキーワードを使えます。

strategy:
  matrix:
    node-version: [16, 18, 20]
    os: [ubuntu-latest, windows-latest]
    exclude:
      - node-version: 16      # Node 16 + Windows の組み合わせはテストしない
        os: windows-latest
    include:
      - node-version: 20      # Node 20 を macOS でも追加で 1 回走らせる
        os: macos-latest

exclude は不要な組み合わせを除外し、include は追加の組み合わせを加えます。テスト範囲を柔軟に制御できます。

OS マトリクス：クロスプラットフォームテスト

プロジェクトが異なる OS 上で動く可能性がある場合（たとえばコマンドラインツール）、OS マトリクスがとても役立ちます。

jobs:
  test:
    runs-on: ${{ matrix.os }}  # OS を動的に指定
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

ここで注意すべき点がいくつかあります。

プラットフォームの違い：Windows と Linux ではファイルパスが違い（\ と /）、一部のコマンドラインツールの挙動も異なります。クロスプラットフォームテストは、こうした問題を事前に発見するのに役立ちます。

コスト管理：GitHub Actions は OS ごとに課金が異なります。Linux は無料で月 2000 分、Windows は Linux の 2 倍消費、macOS は 10 倍です。macOS Runner でテストすると、毎月の枠がすぐに尽きてしまいます。

節約戦略：

• 必要なときだけ macOS をテストする（プロジェクトが本当に macOS で使われる場合など）
• macOS のテストは別のワークフローに分け、workflow_dispatch で手動トリガーする
• パブリックリポジトリは無制限なので、公開できるプロジェクトなら公開がおすすめ

パフォーマンス改善のテクニック

Matrix は並列化できますが、無制限ではありません。GitHub はデフォルトで並列数を制限し、リソースの枯渇を防いでいます。手動で制御することもできます。

strategy:
  max-parallel: 4  # 同時に最大 4 つの Job まで
  matrix:
    node-version: [16, 18, 20, 22]

Matrix の組み合わせが多い場合（10 個以上の Job など）、max-parallel を設定すると一度に走りすぎるのを防ぎ、無料枠の消費を抑えられます。

キャッシュヒットによる高速化：Matrix 内の各 Job はそれぞれ自分のキャッシュを持ちます。setup-node の cache が自動的に処理するので、追加設定は不要です。要点は、package-lock.json と node-version がどちらも安定していれば、キャッシュのヒット率は高くなるということです。

不要なステップを減らす：Matrix 内では各 Job ですべてのステップが走りますが、実際には不要なものもあります。たとえばコードチェック（lint）は通常、複数バージョンのテストを必要としません。

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run lint  # lint は Node 20 で 1 回だけ実行

  test:
    needs: lint  # lint が成功してから test を実行
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16, 18, 20]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

こうすると lint は 1 回だけ、test は 3 バージョンで走ります。効率がより高くなります。

実測データ：私のあるプロジェクトでは、Matrix を使わずに 3 バージョンを直列でテストすると 12 分かかりました。Matrix で並列実行したら総時間は 4 分（最も遅い 1 つのバージョンに依存）でした。8 分の節約で、毎日 10 回ビルドを走らせれば、1 か月で映画 1 本分の時間が浮きます。

第4章：実践経験とトラブルシューティング

前の 3 章では CI パイプラインの設定方法を説明しました。この章では「早見表」をまとめました。セキュリティ、パフォーマンス、トラブルシューティングの 3 つの観点です。問題に遭遇したら直接ここを見れば、かなりの時間を節約できます。

セキュリティ実践チェックリスト

実践	説明	例
permissions を明示的に宣言	デフォルト権限に依存せず、必要な権限を明確に宣言する	permissions: { contents: read }
Secrets で機密情報を保管	API Key、SSH 鍵などをハードコードしない	${{ secrets.API_KEY }}
トリガーブランチを制限	すべてのブランチで CI を走らせず、必要なものだけ	branches: [main]
Action を SHA で参照	バージョンタグではなく具体的な commit SHA を使い、改ざんを防ぐ	actions/checkout@b4ffde65f46336ab88eb53be808477a39b6bc2b1
timeout を設定	ハングによる枠の浪費を防ぐ	timeout-minutes: 15

最後の項目は多くの人が見落とします。Action のバージョン参照です。公式 Action は通常 @v4 のようなタグを使い、アップグレードが楽です。しかしタグは変更できます。理論上、誰かが @v4 を悪意あるコードに向けることが可能です。SHA で参照すれば（@b4ffde65f...）、アップグレードは面倒ですが、より安全です。本番環境のプロジェクトには SHA 参照がおすすめです。

パフォーマンス改善チェックリスト

テクニック	効果	設定方法
依存キャッシュを有効化	インストール時間を 50% 以上節約	cache: 'npm'
install ではなく npm ci を使う	インストールがより速く確実	run: npm ci
timeout-minutes を設定	ハングによる枠の浪費を防ぐ	timeout-minutes: 15
Matrix 並列実行	総時間を 60% 以上削減	strategy.matrix
concurrency で重複ビルドをキャンセル	同一ブランチで最新のものだけ走らせる	concurrency.group: ${{ github.ref }}

concurrency はかなり実用的です。同じブランチに連続で 5 回 push すると、デフォルトでは 5 つのビルドが走ります。concurrency 設定を加えると、前の 4 つはキャンセルされ、最後の 1 回だけ走ります。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true  # 実行中の古いビルドをキャンセル

よくある問題の早見表

エラーメッセージ	原因	解決策
Permission denied	権限不足	permissions 設定を確認し、必要な権限を追加
Cache not found	キャッシュキーが一致しない	cache key を確認し、package-lock.json が変わっていないか確認
npm ERR! network	ネットワークタイムアウト	タイムアウト時間を増やすか、ミラーを使う
Out of memory	Node のメモリ不足	NODE_OPTIONS=--max_old_space_size=4096 を設定
EACCES permission denied	ファイル権限の問題	スクリプト冒頭に chmod +x script.sh を追加
Error: Cannot find module	依存のインストール未完了	npm ci が成功したか確認し、エラーログを確認

よくあるシナリオの対処法をいくつか。

ネットワークタイムアウト：GitHub Runner から npm registry への接続が遅いことがあります。.npmrc でミラーを設定できます。

- name: Configure npm registry
  run: echo "registry=https://registry.npmmirror.com" > .npmrc

メモリ不足：大規模プロジェクトのビルド時に Node がメモリを使い切ることがあります。環境変数を 1 つ追加します。

env:
  NODE_OPTIONS: --max_old_space_size=4096  # Node に 4GB のメモリを割り当てる

キャッシュが効かない：初回はキャッシュが無いのが正常です。package-lock.json が存在し（npm ci はロックファイルが必要）、setup-node の cache パラメータがパッケージマネージャー（npm/pnpm/yarn）と一致していることを確認してください。

結論

いろいろ話しましたが、要は核心となるポイントはいくつかです。YAML ファイル 1 つで CI パイプラインを構築できる。権限宣言は最小権限の原則に従う。環境変数は 3 つの階層で管理する。依存キャッシュでインストール時間を半減できる。Matrix 戦略で複数バージョンの並列テストが簡単になる。

この記事の第1章のワークフローテンプレートをコピーし、Node バージョンとプロジェクトのコマンドを変えるだけで、あなたのプロジェクトに CI を追加できます。まず動かして、それから少しずつ調整しましょう。Matrix 戦略をぜひ試してみてください。たとえ Node バージョンを 2 つだけテストするとしても、並列テストがもたらす効率の良さを体感できます。緑色のチェックがいくつも同時に現れるあの感覚は、なかなか気持ちいいものです。

GitHub Actions を使っていて問題に遭遇したら、コメント欄に書き込んでください。よくある問題を第4章の早見表に追記し、より多くの人が落とし穴を避けられるようにします。