GitHub Actions デプロイ戦略：VPSからクラウドプラットフォームまでのCDパイプライン

深夜3時、GitHub Actionsのログ画面を凝視していました。赤いエラーが次々と流れていきます。「Host key verification failed」。またSSHの問題です。

これで5回目のデプロイ失敗。ローカルテストは全部通っているのに、GitHubにプッシュすると失敗する。その時、強く言いたい気持ちになりましたが、同時に気づいたことがありました。デプロイ戦略の選択は、思っていたよりもずっと複雑なのです。

自分で管理するVPSでも、VercelやCloudflare Pagesのようなホスティングプラットフォームでも、それぞれの方法に落とし穴があります。間違った選択をすると、深夜のトラブルシューティングの回数が増えるだけです。

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

価格を見る →広告

この記事では、GitHub Actionsのいくつかのデプロイ戦略について解説し、あなたに適した方法を見つけるお手伝いをします。

VPS SSHデプロイ：オールドスクールだが信頼性が高い

正直に言うと、最初はVPSデプロイに抵抗がありました。面倒だと思ったのです。SSH鍵、known_hosts、rsyncのパラメータ……やることが多いと。

しかし、いくつかの問題を経験した後、この「オールドスクール」な方法が逆に最も制御しやすいことがわかりました。

SSH鍵の設定：ハードコードしないこと

最もよくある問題は、SSH鍵をどこに置くかです。

初心者はよく秘密鍵を直接workflowファイルに書き込みます。これは大きな間違いです。GitHub Secretsが正しい場所です。

リポジトリの Settings → Secrets → Actions で、SSH_PRIVATE_KEY を追加します。そしてworkflowで次のように使います：

- name: Setup SSH
  uses: webfactory/[email protected]
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

このactionが自動的にssh-agentを起動し、鍵を読み込みます。便利です。

known_hosts：「Host key verification failed」を回避する

SSHで初めてサーバーに接続する際、このホストを信頼するかどうか尋ねられます。CI環境では対話的な質問に対応できないため、事前にサーバーのフィンガープリントをknown_hostsに追加する必要があります。

2つの方法があります：

方法1：actionを使って自動追加

- name: Add server to known hosts
  uses: webfactory/[email protected]
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
    known-hosts: ${{ secrets.SSH_KNOWN_HOSTS }}

SSH_KNOWN_HOSTSの内容は次のように取得できます：

ssh-keyscan -H your-server.com >> known_hosts.txt
# ファイルの内容をGitHub Secretsにコピー

方法2：手動設定

- name: Add server to known hosts
  run: |
    mkdir -p ~/.ssh
    ssh-keyscan -H ${{ secrets.SERVER_IP }} >> ~/.ssh/known_hosts

方法1の方がクリーンで、方法2は迅速なデバッグに適しています。

rsyncかscpか？

デプロイ時のファイル転送には、私はrsyncを使っています。理由はシンプルです：

• 変更されたファイルだけを転送し、時間を節約
• 特定のディレクトリ（node_modulesなど）を除外可能
• 増分同期をサポート

典型的なrsyncコマンド：

- name: Deploy to server
  run: |
    rsync -avz --delete \
      --exclude 'node_modules' \
      --exclude '.git' \
      ./dist/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }}:/var/www/html/

--deleteパラメータは、送信元ディレクトリにないファイルを送信先ディレクトリから削除します。慎重に使用してください。間違えると削除すべきでないものを消してしまう可能性があります。

デプロイ後のコマンド：サービスの再起動

静的サイトなら転送完了で終わりです。しかし、Node.jsアプリをデプロイする場合、サービスを再起動する必要があります。

私はPM2を使ってNodeプロセスを管理しています。デプロイ後に次を実行します：

- name: Restart application
  run: |
    ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
      "cd /var/www/app && pm2 restart all"

または、より確実な方法として、特定のアプリケーションを再起動：

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

15%割引を入手 →広告

- name: Restart application
  run: |
    ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
      "pm2 restart my-app --update-env"

--update-envは環境変数を再読み込みします。設定に変更がある場合に適しています。

クラウドプラットフォームデプロイ：ホスティングサービスの利便性

VPSデプロイの問題は、自分でサーバーを管理しなければならないことです。セキュリティパッチ、SSL証明書の更新、ファイアウォールルール……やることが山ほどあります。

ホスティングプラットフォームなら、ずっと楽になります。コードをプッシュすれば、自動的にビルド、自動的にデプロイ。あなたはコードを書くことに集中できます。

Vercel：フロントエンドプロジェクトの首选

Vercelはフロントエンドプロジェクトをほぼ完璧にサポートしています。Next.js、Astro、React——ワンクリックでデプロイ、設定不要。

ただし、プロジェクトにバックエンドAPIが必要な場合は注意が必要です。VercelのServerless Functionsには実行時間制限があります（無料版は10秒、Pro版は60秒）。これを超えるとタイムアウトします。

純粋な静的サイトやシンプルなAPIなら、Vercelで十分です。複雑なバックエンドサービスは、やはり自分で管理する必要があります。

GitHub ActionsからVercelにデプロイする設定：

name: Deploy to Vercel

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm i -g vercel@latest

      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

VERCEL_TOKENはVercelコンソールから生成し、GitHub Secretsに保存します。

Cloudflare Pages：寛大な無料枠

Cloudflare Pagesの無料枠は、Vercelよりもずっと寛大です。帯域幅は無制限、ビルド回数は月500回——個人プロジェクトには十分すぎます。

さらに、CloudflareのグローバルCDNは本当に速いです。自分でテストしましたが、アジアからのアクセス速度はVercelより安定しています。

デプロイ設定：

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Deploy
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-project
          directory: dist

Cloudflareにはもう一つの利点があります。R2ストレージの無料枠も大きいです。静的リソースをR2に置き、PagesのCDNと組み合わせれば、読み込み速度をかなり向上させられます。

Netlify：老舗の安定した選択肢

Netlifyはあまり使っていませんが、老舗のホスティングプラットフォームで、エコシステムは成熟しています。

デプロイ設定は同様：

- name: Deploy to Netlify
  uses: netlify/actions/cli@master
  with:
    args: deploy --prod
  env:
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
    NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

NetlifyのForm handling機能は実用的です。フォーム送信を自動処理してくれ、シンプルなマーケティングページに適しています。

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

今すぐ始める →広告

ホスティングプラットフォームの制限

ただし、ホスティングプラットフォームも万能ではありません。

よくある制限：

1. ビルド環境の制限：メモリ、CPUに上限があり、大規模プロジェクトはビルド失敗する可能性
2. カスタマイズ度が低い：nginxの設定を変えたい？できません
3. プラットフォームの存続に依存：プラットフォームが廃業したりポリシーが変わったりすると、移行が必要
4. 国内からのアクセス問題：一部のプラットフォームは国内からのアクセスが不安定（Cloudflareは改善されていますが）

プロジェクトに完全な制御が必要なら、やはりVPSに戻る必要があります。

ハイブリッド戦略：柔軟性と制御の両立

多くのプロジェクトは「純粋な静的」でも「純粋なバックエンド」でもありません。フロントエンドはNext.js、バックエンドはデータベースに接続し、cronジョブを実行する必要がある……。

このような場合、ハイブリッドデプロイが最適解かもしれません。

静的ページホスティング + APIデプロイをVPSへ

典型的なアーキテクチャ：

• 静的ページ（HTML/CSS/JS）をCloudflare PagesやVercelにデプロイ
• Node.js APIサービスを自分のVPSにデプロイ
• データベースもVPS上（またはSupabase/PlanetScaleなどのホスティングを使用）

メリットは、それぞれの利点を活かせること：

• フロントエンドはCDNの高速化と自動HTTPSを享受
• バックエンドは完全な制御権を持ち、ホスティングプラットフォームの制限を受けない
• データベースへのアクセス遅延が低い（APIとデータベースが同じマシン上）

GitHub Actionsのマルチステージデプロイ

1つのworkflowで2箇所にデプロイ：

name: Hybrid Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-path: ./dist
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist

  deploy-frontend:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: my-frontend
          directory: dist

  deploy-backend:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup SSH
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
      - name: Deploy API to VPS
        run: |
          rsync -avz --delete \
            --exclude 'node_modules' \
            ./api/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }}:/var/www/api/
      - name: Restart API service
        run: |
          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
            "cd /var/www/api && npm install && pm2 restart api"

このworkflowには3つのjobがあります：

1. build：プロジェクトをビルドし、静的ファイルを生成
2. deploy-frontend：静的ファイルをCloudflare Pagesにデプロイ
3. deploy-backend：APIをVPSにデプロイし、サービスを再起動

needs: buildは、デプロイjobがビルド完了後に実行されることを保証します。upload-artifactとdownload-artifactは、job間でビルド成果物を受け渡します。

環境変数の分離

ハイブリッドデプロイの課題：フロントエンドとバックエンドの環境変数が異なります。

フロントエンドはAPIアドレスを知る必要があり、バックエンドはデータベースパスワードを知る必要があります。

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

価格を見る →広告

私のやり方：

# フロントエンドjob
- name: Set frontend env
  run: |
    echo "API_URL=https://api.mydomain.com" >> $GITHUB_ENV

# バックエンドjob
- name: Deploy with env
  run: |
    ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_IP }} \
      "cd /var/www/api && pm2 restart api --update-env DATABASE_URL=${{ secrets.DATABASE_URL }}"

機密情報（データベースパスワード、APIトークン）は常にGitHub Secrets経由で。機密でない情報（APIアドレス）はworkflowに書けます。

実践設定例

以下は、前述の要点をすべてカバーする完全なVPSデプロイworkflowです。

完全なworkflowファイル

name: Deploy to VPS

on:
  push:
    branches: [main]
  workflow_dispatch:  # 手動トリガーデプロイ

env:
  NODE_VERSION: '20'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist
          retention-days: 1

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist

      - name: Setup SSH
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Add server to known hosts
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan -H ${{ secrets.SERVER_HOST }} >> ~/.ssh/known_hosts

      - name: Deploy files
        run: |
          rsync -avz --delete \
            --exclude '.htaccess' \
            ./dist/ ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }}:${{ secrets.DEPLOY_PATH }}

      - name: Verify deployment
        run: |
          ssh ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }} \
            "ls -la ${{ secrets.DEPLOY_PATH }}"

      - name: Send deployment notification
        if: always()
        run: |
          curl -X POST "${{ secrets.NOTIFICATION_WEBHOOK }}" \
            -H "Content-Type: application/json" \
            -d '{"text": "Deployment completed: ${GITHUB_SHA}"}'

設定が必要なSecrets

よくある問題のトラブルシューティング

デプロイ失敗時、ログを見ると混乱しやすいです。情報が多すぎて。

私の調査順序：

1. SSH接続の問題：「Setup SSH」と「Add server to known hosts」ステップを確認
   • 失敗した場合、鍵の形式、known_hostsの内容を確認
2. rsync転送の問題：「Deploy files」ステップを確認
   • 失敗した場合、パスが存在するか、権限が正しいか確認
3. サービス再起動の問題：「Verify deployment」ステップを確認
   • 失敗した場合、対象パスにファイルがあるか確認

1つのテクニック：失敗したステップの後にデバッグ出力を追加。

- name: Debug SSH connection
  if: failure()
  run: |
    echo "SSH config:"
    cat ~/.ssh/config || echo "No config file"
    echo "Known hosts:"
    cat ~/.ssh/known_hosts || echo "No known_hosts file"
    ssh -v ${{ secrets.SERVER_USER }}@${{ secrets.SERVER_HOST }} echo "Connection test"

ssh -vは詳細なログを出力し、問題箇所を特定できます。

まとめ

これだけ書きましたが、実は一言で言えます。完璧なデプロイ方法はなく、あなたのプロジェクトに最適な方法があるだけです。

選択のアドバイス：

• 純粋な静的サイト（ブログ、ドキュメント）：Cloudflare PagesまたはVercel、手間いらず
• シンプルなAPI + フロントエンド：ホスティングプラットフォームで十分、VPSで苦労しない
• 複雑なバックエンド + データベース：VPSまたはクラウドサーバー、制御権が重要
• ハイブリッドアーキテクチャ：フロントエンドホスティング + バックエンドVPS、それぞれの利点を活かす

どの方法を選んでも、GitHub Actionsの設定パターンは似ています：ビルド → 転送 → 再起動。この3つのステップを明確に分けておけば、トラブルシューティングの際に混乱しません。

もう1つ：デプロイ失敗時に慌てないこと。ログをセグメントごとに見て、SSH接続の問題かコマンド実行の問題かを先に特定する。デバッグステップを追加すれば、問題はすぐに明らかになります。

次回、深夜3時にデプロイが失敗しても、より早く原因を見つけられることを願っています。

5 min read · 公開日: 2026年4月7日 · 更新日: 2026年4月8日

Easton

技術開発