Next.js CI/CD 実践ガイド：GitHub Actions で実現する自動テストとデプロイ

金曜日の午後5時半、私はターミナルに流れるログを見つめながら、指は機械的に git pull && npm install && npm run build && pm2 restart を叩いていました。これが今日3回目のデプロイです。午前中に小さなバグを直し、昼にAPIを最適化し、今はスタイルを少し修正したところ。サーバーは3台あるので、それぞれのサーバーで同じ操作を繰り返さなければなりません。

最後の一台を終えた頃には、時計の針は7時を回っていました。

その日の帰り道、もっと良い方法があるはずだと考えました。コードを修正するたびにサーバーにログインして同じ操作を繰り返したくないし、ましてや再起動を忘れて古いバージョンのまま放置してしまうなんてミスもしたくない。正直なところ、テストを実行するのさえ忘れがちでした。コードを直して「早く公開したい」という一心でデプロイしてしまい、後でバグが見つかってまたやり直す、なんてこともしばしば。

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

15%割引を入手 →広告

その後、CI/CD と GitHub Actions に出会い、ワークフローが一変しました。今では GitHub にコードをプッシュするだけ。残りのテスト、ビルド、デプロイはすべて自動で行われます。コーヒーを淹れている間に、新しいバージョンが公開されています。

もしあなたも手動デプロイに悩まされているなら、この記事で GitHub Actions を使った Next.js の自動デプロイフローの構築方法を共有します。基礎的な設定から完全な実践例、私が踏んだ「地雷」とその解決策まで、すべてお話しします。

なぜ CI/CD が必要なのか

手動デプロイの苦しみ

私が Next.js プロジェクトを始めたばかりの頃、デプロイの手順はこんな感じでした：ローカルでコードを書き、テストし、SSH でサーバーにログインし、git pull でコードを引っぱり、npm install で依存関係を入れ、npm run build でビルドし、最後に pm2 restart でサービスを再起動。順調にいっても十数分はかかります。

しかし、現実はそう順調ではありません。

ある時、3台のサーバーにデプロイしていたのですが、最初の2台は成功したものの、3台目は SSH 接続が切れていて更新されていないことに気づきませんでした。翌日、ユーザーから「サイトが新しいバージョンだったり古いバージョンだったりする」というフィードバックが来ました。ロードバランサーが更新されていないサーバーにリクエストを振り分けていたのです。またある時は、コード修正に興奮してテストをすっ飛ばしてデプロイし、致命的なバグを本番環境に送り込んでしまい、冷や汗をかきながら緊急ロールバックしたこともあります。

さらに厄介なのが、複数サーバーでのビルド問題です。Next.js はビルドごとに新しい build ID を生成します。3台のサーバーでそれぞれビルドすると、ID がバラバラになってしまいます。ロードバランサーがユーザーのリクエストを異なるサーバーに振り分けると、Next.js は ID の変化を検知してハードリフレッシュ（完全な再読み込み）をトリガーしてしまいます。ユーザー体験は最悪です。

CI/CD は何を解決するのか

要するに、CI/CD はこれらの反復的でエラーが発生しやすいプロセスを自動化します。

**CI（継続的インテグレーション）**はテストを担当します。コードをプッシュするたびに、自動的にテスト（単体テスト、型チェック、コード規約チェック）を実行します。テストが通らなければデプロイされません。これにより、バグのあるコードが本番環境に出るのを防げます。

**CD（継続的デプロイ）**はビルドとデプロイを担当します。テストが通れば、自動的にビルドを開始し、完了したらサーバーにデプロイします。この間、指一本動かす必要はありません。

実際の効果は？ 私の現在のワークフローはこうです：ローカルでコードを書く → GitHub にプッシュ → 自動テスト → 自動ビルド → 自動デプロイ。プッシュしてから公開まで約5分。その間監視する必要もありません。水を飲みに行って戻ってくれば、新バージョンが公開されています。

もう一つの利点は追跡可能性です。各デプロイには完全なログが残り、どのコミットがトリガーしたか、テスト結果はどうだったか、どのサーバーにデプロイされたかが一目瞭然です。問題が起きてもすぐに原因を特定でき、手探りで調べる必要がありません。

GitHub Actions 基礎設定

仕組みを理解する

GitHub Actions に初めて触れた時、workflow、job、step といった用語に混乱しました。でも実はシンプルです。

**Workflow（ワークフロー）**は一連の自動化プロセス全体を指します。例えば「テスト+ビルド+デプロイ」が1つのワークフローです。これは .github/workflows ディレクトリ内の YAML ファイルで定義します。

**Job（ジョブ）**はワークフロー内の独立したタスクです。例えば「テスト」ジョブと「デプロイ」ジョブを作れます。ジョブは並列実行したり、依存関係を設定して順番に実行したりできます。

**Step（ステップ）**はジョブ内の具体的な操作です。「コードをプルする」「依存関係をインストールする」「テストを実行する」などがステップにあたります。

トリガー条件も柔軟です。main ブランチへのプッシュで実行したり、Pull Request 作成時のみ実行したり、あるいは毎日深夜に自動実行するようスケジュールすることも可能です。

最初の Workflow を作成

まずプロジェクトのルートディレクトリに .github/workflows フォルダを作成し、ci-cd.yml というファイルを作ります。最も基本的な設定は以下のようになります：

name: CI/CD Pipeline

# トリガー条件: main ブランチへの push で実行
on:
  push:
    branches: [main]

jobs:
  build:
    # 最新の Ubuntu 環境で実行
    runs-on: ubuntu-latest

    steps:
      # ステップ1: コードを取得
      - uses: actions/checkout@v4

      # ステップ2: Node.js 環境をセットアップ
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      # ステップ3: 依存関係をインストール
      - name: Install dependencies
        run: npm ci

      # ステップ4: プロジェクトをビルド
      - name: Build
        run: npm run build

この設定は、「main ブランチにコードがプッシュされるたびに、Ubuntu システム上でコード取得、Node.js 導入、依存インストール、ビルドを実行する」という意味です。

このファイルを GitHub にコミットすると、リポジトリの “Actions” タブでワークフローの実行状況を確認できます。初めてあの緑色のチェックマーク（成功）を見た時は、ちょっとした達成感がありました。

Secrets で機密情報を守る

サーバーへのデプロイには、サーバーの IP、SSH キー、API トークンなどの機密情報が必要です。これらを YAML ファイルに直接書いてはいけません。GitHub にコミットすると世界中に公開されてしまいます。

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

正しい方法は GitHub の Secrets 機能を使うことです。リポジトリの Settings → Secrets and variables → Actions で “New repository secret” をクリックしてキーを追加します。例えば SERVER_HOST という名前でサーバーの IP アドレスを保存します。

そしてワークフロー内で ${{ secrets.SERVER_HOST }} のように参照します。GitHub は実行時にこれを実際の値に置き換えます。ログ上では伏せ字（***）になり、漏洩することはありません。

自動テストフローの構築

テスト環境の設定

テストに関して私の考えは「自動化できるものは手動でやるな」です。ESLint（コード規約）、TypeScript（型チェック）、Jest（単体テスト）を含むテストフローを構成し、大半の問題をここで食い止めます。

完全なテスト job の設定を見てみましょう：

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'  # npm 依存関係をキャッシュして次回以降を高速化

      - name: Install dependencies
        run: npm ci

      - name: Lint check
        run: npm run lint

      - name: Type check
        run: npm run type-check

      - name: Run tests
        run: npm run test -- --coverage

ここで小技：cache: 'npm' を設定すると自動的に node_modules をキャッシュしてくれるので、2回目以降の実行時に依存関係のダウンロード時間が短縮され、数分の節約になります。

テストフロー高速化のコツ

最初はテストに10分以上かかり、コミットのたびに待つのが苦痛でした。最適化の結果、今では3分で終わります。

コツ1：キャッシュ
npm キャッシュに加え、Next.js のビルドキャッシュも保存します：

- name: Cache Next.js build
  uses: actions/cache@v3
  with:
    path: |
      ~/.npm
      .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}

これで Next.js は変更されたページだけを再ビルドすればよくなり、大幅に速くなります。

コツ2：並列実行
テスト間に依存関係がなければ、複数の job に分割して並列実行できます：

jobs:
  lint:
    runs-on: ubuntu-latest
    steps: [...]  # lint だけ実行

  test:
    runs-on: ubuntu-latest
    steps: [...]  # 単体テストだけ実行

  type-check:
    runs-on: ubuntu-latest
    steps: [...]  # 型チェックだけ実行

これら3つの job は同時に開始されるので、総所要時間は3つの合計ではなく、一番遅い job の時間だけで済みます。

私が踏んだ「地雷」

一度、ローカルではテストが通るのに GitHub Actions では失敗するという事態に陥りました。半日デバッグして分かったのは、GitHub Actions が Pull Request のコードを取得する際、デフォルトで PR ブランチをターゲットブランチにマージした「仮想的なコミット」を作成してチェックアウトするため、ローカルとは微妙に異なる状態になっていたことでした。

解決策は、checkout 時にパラメータを追加することです：

- uses: actions/checkout@v4
  with:
    ref: ${{ github.head_ref }}  # PR ブランチの元のコードを使用

もう一つはテストのタイムアウトです。E2E テストなどは時間がかかるため、デフォルトのタイムアウトでは足りないことがあります。job に長めのタイムアウトを設定しましょう：

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # デフォルトは 6時間（長すぎ）ですが、適切に設定しましょう

自動デプロイフローの構築

Vercel へのデプロイ：最も簡単な方法

プロジェクトが Vercel にあるなら簡単です。Vercel と GitHub はネイティブに統合されているので、リポジトリを連携するだけで push 時に自動デプロイされます。

しかし、「テストが通った場合のみデプロイしたい」といった細かい制御が必要な場合は、Vercel 公式の GitHub Action を使います：

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: test  # テスト job が完了してから実行
    if: github.ref == 'refs/heads/main'  # main ブランチのみデプロイ

    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'  # 本番環境へデプロイ

Vercel の管理画面で Token を生成し、プロジェクト設定から Org ID と Project ID を取得して GitHub Secrets に保存します。

Vercel の良いところは、PR ごとにプレビュー環境を自動作成してくれる点です。PR を出すと、一時的な環境にデプロイされ、プレビューリンクが発行されるので、変更内容をすぐに確認できて便利です。

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

価格を見る →広告

自前サーバーへのデプロイ：柔軟だが少し複雑

私自身のプロジェクトは、より自由な制御を求めて自前サーバーに配置しています。この場合、SSH 接続を構成し、GitHub Actions からサーバーコマンドを実行させる必要があります。

まずローカルで SSH キーペアを生成します：

ssh-keygen -t ed25519 -C "github-actions"

公開鍵をサーバーの ~/.ssh/authorized_keys に追加し、秘密鍵を GitHub Secrets（例：SSH_PRIVATE_KEY）に追加します。

そしてデプロイ job を設定します：

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/my-nextjs-app
            git pull origin main
            npm install
            npm run build
            pm2 restart nextjs-app

この設定は、SSH でサーバーに入り、最新コードを取得し、依存関係を入れ、ビルドし、アプリを再起動します。完全に自動化されており、手動ログインは不要です。

複数サーバーでの Build ID 不一致問題の解決

ロードバランシングのために複数台のサーバーにデプロイする場合、重要な問題があります。各サーバーで個別にビルドすると build ID が異なり、ユーザーがアクセスするたびにページがリフレッシュされる問題が発生します。

解決策は「一箇所でビルドし、成果物を配布する」ことです。以下のように設定します：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build

      # ビルド成果物をアップロード
      - name: Upload build artifacts
        uses: actions/upload-artifact@v3
        with:
          name: next-build
          path: |
            .next
            public

  deploy:
    runs-on: ubuntu-latest
    needs: build
    strategy:
      matrix:
        server: [server1, server2, server3]  # 複数サーバー

    steps:
      # ビルド成果物をダウンロード
      - name: Download build artifacts
        uses: actions/download-artifact@v3
        with:
          name: next-build

      # 各サーバーへデプロイ
      - name: Deploy to ${{ matrix.server }}
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets[format('{0}_HOST', matrix.server)] }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: ".next,public"
          target: "/var/www/my-nextjs-app"

これで一度だけビルドを行い、同じ成果物を3台のサーバーに配布するため、build ID が完全に一致します。

最適化とベストプラクティス

失敗時の通知

自動化は素晴らしいですが、失敗することもあります。失敗したことに気づく仕組みが必要です。Slack やメール等で通知を受け取れます。Slack の例：

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      [...デプロイ手順...]

      # 失敗時に Slack 通知
      - name: Notify on failure
        if: failure()
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: 'デプロイ失敗！確認してください。'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
          channel: '#deploy-notifications'

これで失敗したら即座に通知が飛んできます。

ブランチ戦略：開発と本番の分離

実際のプロジェクトでは、環境ごとにブランチを分けます。develop ブランチはテスト環境へ、main ブランチは本番環境へデプロイします。

on:
  push:
    branches:
      - main      # 本番環境
      - develop   # テスト環境

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    steps:
      - [...テスト環境へのデプロイ...]

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - [...本番環境へのデプロイ...]

また、本番デプロイには承認フローを入れることもできます。GitHub Actions の Environment 機能を使います：

jobs:
  deploy-production:
    runs-on: ubuntu-latest
    environment:
      name: production  # 承認が必要な環境
    steps: [...]

こうすると、本番デプロイの前に実行が一時停止し、指定された承認者が「Approve」ボタンを押すまで待機します。

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

15%割引を入手 →広告

ロールバックメカニズム

万一問題が起きたときのために、素早く以前のバージョンに戻せる仕組みが必要です。

シンプルな方法は、デプロイ時にタグを打ち、Git の機能で特定バージョンをデプロイする手動ワークフローを用意することです：

on:
  workflow_dispatch:  # 手動トリガー
    inputs:
      tag:
        description: 'ロールバック先のタグ'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.tag }}  # 指定タグを使用

      - name: Deploy
        [...通常のデプロイフロー...]

GitHub Actions の画面から “Run workflow” をクリックし、タグを入力すれば即座にロールバックできます。

環境変数の管理

Next.js プロジェクトでは API URL や DB 接続情報などの環境変数が必要です。これらを Git に入れてはいけません。

1. GitHub Secrets に機密情報を保存
2. ワークフロー内で環境変数として注入
3. Next.js ビルド時に読み込む

- name: Build
  run: npm run build
  env:
    NEXT_PUBLIC_API_URL: ${{ secrets.API_URL }}
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

これで環境ごとに異なる変数を適用でき、コードの修正は不要です。

実践ケース：完全な設定例

これまでの要素を組み合わせた完全な設定例です。テスト、ビルド、デプロイの全フローを含みます：

name: Next.js CI/CD

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

jobs:
  # Job 1: コードチェックとテスト
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint check
        run: npm run lint

      - name: Type check
        run: npm run type-check

      - name: Run tests
        run: npm run test -- --coverage

  # Job 2: ビルド
  build:
    runs-on: ubuntu-latest
    needs: test  # テスト通過後のみ実行
    if: github.event_name == 'push'  # PR時はビルドしない

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Cache dependencies and build
        uses: actions/cache@v3
        with:
          path: |
            ~/.npm
            .next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build
        env:
          NEXT_PUBLIC_API_URL: ${{ secrets.API_URL }}

      # デプロイ用に成果物をアップロード
      - name: Upload build artifacts
        uses: actions/upload-artifact@v3
        with:
          name: next-build
          path: |
            .next
            public
            package.json

  # Job 3: テスト環境デプロイ
  deploy-staging:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/develop'

    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v3
        with:
          name: next-build

      - name: Deploy to staging server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.STAGING_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/staging
            pm2 stop nextjs-app || true
            rm -rf .next public
            pm2 start npm --name "nextjs-app" -- start
            pm2 save

      - name: Notify Slack
        if: always()
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: 'テスト環境デプロイ ${{ job.status == "success" && "成功" || "失敗" }}'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

  # Job 4: 本番環境デプロイ
  deploy-production:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    environment:
      name: production  # 手動承認が必要

    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v3
        with:
          name: next-build

      - name: Deploy to production server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.PROD_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/production
            pm2 stop nextjs-app || true
            rm -rf .next public
            pm2 start npm --name "nextjs-app" -- start
            pm2 save

      - name: Notify Slack
        if: always()
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: '本番環境デプロイ ${{ job.status == "success" && "成功" || "失敗" }}'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

この設定では、PR 時はテストのみ実行。develop ブランチへのプッシュでテスト環境へ自動デプロイ。main ブランチへのプッシュで本番環境へデプロイ（承認待ち）。そして結果を Slack 通知します。

GitHub リポジトリ設定で以下の Secrets が必要です：

• API_URL: API アドレス
• STAGING_HOST / PROD_HOST: サーバー IP
• SERVER_USER: SSH ユーザー
• SSH_PRIVATE_KEY: SSH 秘密鍵
• SLACK_WEBHOOK: Slack Webhook URL

これで全て自動化されます。あなたはコードを書いてプッシュするだけ。

まとめ

手動デプロイから自動化への移行は、開発体験を劇的に向上させます。退屈なコマンド入力や、テスト忘れの不安、デプロイ完了を待つ時間から解放されます。

GitHub Actions の設定は最初は手間に感じるかもしれませんが、その価値は十分にあります。まずは「テストとビルド」の自動化から始め、徐々にデプロイ、通知、ロールバック機能を追加していくのがおすすめです。

今では、以前どうやって手動でデプロイしていたのか思い出せないほどです。コードをプッシュし、コーヒーを飲み、戻ってきたら新機能がユーザーに届いている——この快適さを、ぜひあなたも体験してください。

7 min read · 公開日: 2025年12月20日 · 更新日: 2026年1月22日

Easton

技術開発