【ITニュース解説】Automate Your Laravel Deployment on a VPS Using GitHub Actions: A Beginner's Guide

システムエンジニアを目指す皆さんにとって、開発したアプリケーションをインターネット上で公開する「デプロイ」という作業は非常に重要である。特に、頻繁にアプリケーションを更新する場合、このデプロイ作業を手作業で行うのは手間がかかり、ミスも起こりやすいため、多くの時間と労力を消費してしまう。今回の記事では、このデプロイ作業を自動化する方法、具体的にはLaravelアプリケーションをVirtual Private Server（VPS）にGitHub Actionsを使って自動デプロイする手法が解説されている。

この自動化の仕組みは、一言で言えば「GitHubのリポジトリにコードをプッシュするだけで、あなたのサーバー上のアプリケーションが自動的に最新の状態に更新される」というものである。これにより、手動でサーバーにログインし、変更をプルしたり、必要なコマンドを実行したりといった面倒な作業から解放される。

なぜGitHub Actionsを使ってデプロイを自動化するのか、それにはいくつかの大きな利点がある。まず「自動化」により、コードをプッシュするだけでサーバーが自動的に更新されるため、作業効率が大幅に向上する。次に「セキュリティ」の面では、サーバーへの接続に必要なSSHキーなどの機密情報をGitHubの「シークレット」機能に安全に保管できる。これにより、機密情報が公開されたコードに含まれる心配がない。さらに「柔軟性」があり、テスト環境、ステージング環境、本番環境など、目的別に異なるデプロイのワークフローを自由にカスタマイズできる。最後に「可視性」も高く、デプロイの進行状況や結果をGitHubの「Actions」タブで簡単に確認できるため、問題が発生した際の原因特定も容易である。

このデプロイ自動化を実現するためには、いくつかの前提条件がある。まず、デプロイしたいLaravelプロジェクトが格納されたGitHubリポジトリが必要である。これは通常、mainブランチで管理されていることを想定している。次に、デプロイ先となるVPSが必要で、UbuntuなどのLinuxディストリビューションが動作しており、PHP 8.3以上、Composer、GitといったLaravelアプリケーションの動作に必要なソフトウェアがインストールされている必要がある。また、Laravelアプリケーション自体がVPS上にクローンされ、実行可能な状態（例えば/var/www/your-appディレクトリに配置）で、NginxやApacheといったWebサーバーが適切に設定されていることも重要である。もしアプリケーションがキューワーカーを利用している場合は、Supervisorなどのプロセス管理ツールも必要となる。

それでは、具体的な手順を見ていこう。

ステップ1：SSHキーのセットアップ GitHub ActionsがあなたのVPSに安全に接続するためには、SSH（Secure Shell）という仕組みを使う。まず、VPS上でSSHキーペアを生成する。これは、秘密鍵と公開鍵の組み合わせで、公開鍵をVPSの認証リストに追加し、秘密鍵をGitHub Actionsに登録することで、パスワードなしで安全な接続を確立する。 VPSにSSHでログインした後、ssh-keygen -t ed25519 -C "your_email@example.com"コマンドを実行し、指示に従ってキーペアを作成する。これにより、通常~/.ssh/id_ed25519という秘密鍵ファイルと~/.ssh/id_ed25519.pubという公開鍵ファイルが生成される。 次に、生成された公開鍵の内容をVPSの~/.ssh/authorized_keysファイルに追加し、このファイルのパーミッションを適切に設定する。これで、この公開鍵に対応する秘密鍵を持っていれば、VPSにログインできるようになる。最後に、cat ~/.ssh/id_ed25519コマンドで秘密鍵の内容をコピーし、後でGitHubのシークレットとして登録するために手元に控えておく。この秘密鍵は非常に重要であり、他人に知られないように厳重に管理する必要がある。

ステップ2：VPSへのリポジトリのクローン アプリケーションのコードをVPS上で管理するために、GitHubリポジトリをVPSにクローンする。もし既にクローン済みであればこのステップはスキップできる。 まず、アプリケーションを配置するディレクトリ（例:/var/www/your-app）を作成し、適切な所有権を設定する。その後、そのディレクトリに移動してgit clone git@github.com:yourusername/your-repo.git .コマンドを実行し、リポジトリのコードをクローンする。 クローンが完了したら、Composerを使ってLaravelの依存関係をインストールし、環境設定ファイルである.envファイルを用意する。この.envファイルには、データベースの接続情報など、アプリケーションが動作するために必要な設定を記述する。最後に、php artisan key:generateでアプリケーションキーを生成し、php artisan migrateでデータベースのマイグレーションを実行する。

ステップ3：デプロイスクリプトの作成 デプロイ自動化の核となるのが、VPS上で実行されるデプロイスクリプトである。このスクリプトは、新しいコードのプル、依存関係の更新、キャッシュのクリア、データベースマイグレーションの実行、サービスの再起動といった一連のデプロイ作業を自動的に行う。 アプリケーションのルートディレクトリ（例:/var/www/your-app）にdeploy.shという名前でシェルスクリプトファイルを作成する。スクリプトの内容は以下のようになる。 まず、set -eと記述することで、スクリプト内のコマンドが一つでも失敗したら即座にスクリプトを終了させるように設定し、予期せぬエラーで不完全なデプロイが行われるのを防ぐ。 次に、現在のアプリケーションをメンテナンスモードに移行するコマンドphp artisan downを実行する。これにより、デプロイ中にユーザーが古いコードや不完全な状態のアプリケーションにアクセスするのを防ぐ。 その後、git fetch origin mainとgit reset --hard origin/mainコマンドでGitHubリポジトリの最新のコードをサーバーにプルし、ローカルの変更をすべて上書きして最新の状態にする。 続いてcomposer installコマンドでPHPの依存関係を更新し、php artisan cache:clear, php artisan config:cache, php artisan route:cache, php artisan view:cacheといったコマンドでアプリケーションのキャッシュをクリアし、再構築する。これは、新しいコードがキャッシュを正しく利用できるようにするために重要である。 データベースの構造に変更があった場合は、php artisan migrate --forceコマンドでデータベースマイグレーションを実行し、データベースを最新の状態に保つ。キューワーカーを使用している場合は、php artisan queue:restartでワーカーを再起動し、新しいコードで処理を行うようにする。 これらの更新作業が完了したら、php artisan upでアプリケーションをメンテナンスモードから解除し、ユーザーがアクセスできるようにする。最後に、service php8.3-fpm reloadコマンド（PHPのバージョンに合わせて調整が必要）でPHP-FPMサービスを再読み込みし、OPcacheなどのPHPのキャッシュを更新して、新しいコードが確実に適用されるようにする。 このスクリプトを作成したら、chmod +x deploy.shコマンドで実行権限を与え、./deploy.shコマンドで手動でテストを実行し、問題がないことを確認する。

ステップ4：GitHub Actionsワークフローの設定 いよいよGitHub Actionsの設定である。リポジトリのルートに.github/workflowsディレクトリを作成し、その中にdeploy.ymlという名前のファイルを作成する。このYAMLファイルがデプロイの自動化の手順を定義する。 ワークフローはname: Deploy to Productionという名前を持ち、on:pushトリガーによって、mainブランチへのプッシュがあった場合に自動的に実行されるように設定されている。 jobsセクションには、実行されるジョブ（一連のステップ）を定義する。ここではdeployというジョブがあり、これはubuntu-latestという最新のUbuntu環境で実行される。 stepsセクションには、具体的な処理のリストが記述される。

1. Checkout Repository: actions/checkout@v3というGitHub Actionsの既存のアクションを利用して、リポジトリのコードをワークフローの実行環境にチェックアウトする。
2. Setup SSH: webfactory/ssh-agent@v0.5.4というアクションを使って、GitHubシークレットに保存されたSSH秘密鍵をワークフローの実行環境に登録し、SSH接続ができるように準備する。
3. Deploy to VPS: appleboy/ssh-action@masterというアクションを利用して、VPSへのSSH接続を行い、作成したデプロイスクリプトを実行する。このステップでは、接続先のホストIPアドレス、ユーザー名、SSH秘密鍵、そしてデプロイスクリプトが存在するパスといった情報が、すべてGitHubシークレットから安全に取得されて利用される。scriptの部分には、VPS上で実行するコマンド、つまりアプリケーションディレクトリへの移動と./deploy.shスクリプトの実行が記述される。 このdeploy.ymlファイルをコミットし、mainブランチにプッシュすることで、GitHub Actionsのワークフローがリポジトリに登録される。

ステップ5：GitHub Secretsの設定 GitHub Actionsワークフローで利用する機密情報（SSH秘密鍵、VPSのIPアドレス、ユーザー名、デプロイパス）は、リポジトリの「Settings」→「Secrets and variables」→「Actions」セクションに「New repository secret」として登録する。 具体的には、以下の4つのシークレットを設定する。

• DEPLOY_SERVER_KEY: ステップ1で取得したSSH秘密鍵（id_ed25519の内容）を貼り付ける。
• DEPLOY_SERVER_IP: あなたのVPSのIPアドレスを記述する。
• DEPLOY_SERVER_USER: VPSにログインするためのユーザー名を記述する。
• DEPLOY_PATH: VPS上のLaravelアプリケーションのルートディレクトリのフルパス（例:/var/www/your-app）を記述する。 これらのシークレットはワークフローからのみアクセス可能で、外部に公開されることはないため、安全に機密情報を管理できる。

ステップ6：デプロイのテスト すべての設定が完了したら、実際にデプロイをテストする。ローカル環境でアプリケーションのコードにごく小さな変更（例えば、ビューファイルの内容を少し変更するなど）を加え、それをコミットし、mainブランチにプッシュする。 プッシュ後、GitHubリポジトリの「Actions」タブに移動すると、新しいワークフローが実行されているのが確認できる。ワークフローが成功すれば、あなたのVPS上のアプリケーションが自動的に更新されているはずである。VPSにSSHでログインし、/var/www/your-appディレクトリの内容を確認したり、Webブラウザでアプリケーションにアクセスしたりして、変更が正しく反映されているかを確認する。 もしデプロイが失敗した場合は、GitHub Actionsのログを詳細に確認することで、どこで問題が発生したかを特定できる。一般的な問題としては、SSHキーの設定ミス、ファイルやディレクトリのパーミッション不足、PHP-FPMサービスのバージョン違いなどが挙げられる。

ベストプラクティス 本番環境でのデプロイをより安全かつ効率的に行うためのいくつかの推奨事項がある。まず、デプロイ前に必ず「テスト環境」や「ステージング環境」でデプロイをテストし、問題がないことを確認することが重要である。また、データベースのマイグレーションを実行する前には、必ずVPSやデータベースの「バックアップ」を取得しておくべきである。万が一デプロイで問題が発生した場合に、すぐに元の状態に戻せるようにするためである。エラー監視ツール（Sentryなど）を利用して、アプリケーションのエラーを早期に検出し、迅速に対応できるようにすることも大切である。さらに、本番環境でユーザーへの影響を最小限に抑える「ゼロダウンタイムデプロイ」を実現したい場合は、Laravel ForgeやEnvoyerといった専用のデプロイツールを検討することも有効である。セキュリティをさらに強化するためには、SSHアクセスをGitHub ActionsランナーのIPアドレス範囲に限定することも推奨される。

この記事で解説されている手順を踏むことで、手作業でのデプロイに伴う手間やリスクを大幅に削減し、より効率的で信頼性の高い開発ワークフローを確立できる。この自動化されたデプロイ環境は、日々の開発作業を大きく改善し、システムエンジニアとしての生産性向上に貢献するだろう。この知識を活かして、より良いアプリケーション開発に挑戦してほしい。