Laravel GitHub Actions CI/CD完全ガイド｜自動テスト・Pest連携・静的解析と自動デプロイ設計

LaravelでWebアプリケーションを開発・運用する際、「ローカル環境では動いていたのに本番環境でエラーが発生した」「プルリクエストのレビューで構文ミスやテスト漏れの見落としがあった」「手動デプロイの手順ミスでサービス停止を引き起こした」といったトラブルを経験したエンジニアは少なくありません。

近年のLaravel開発において、これらの課題を根本から解決するデファクトスタンダードが GitHub Actions を活用した CI/CD（継続的インテグレーション / 継続的デリバリー）パイプラインの自動化 です。

本ガイドでは、PHP 8.2〜8.4環境に対応した基本的なCI環境の構築から、高速テスティングフレームワーク「Pest」による並列テスト実行、Laravel Pintによるコードスタイル自動補正、Larastan（PHPStan）による静的解析、そしてSSHやDeployerを組み合わせた安全なゼロダウンタイム自動デプロイの設計までを一気通貫で徹底解説します。

実務の現場ですぐに導入できるよう、コピペでそのまま動くYAML設定の全文と、運用時につまずきやすいメモリ枯渇やデータベース接続エラーのトラブルシューティングまで網羅しました。堅牢で手戻りのない開発パイプラインの構築にお役立てください。

—

## Laravel開発にGitHub Actionsを導入するメリットとCI/CDの全体像

GitHub Actionsは、GitHubリポジトリと完全に統合された自動化プラットフォームです。特別な外部CI/CDサーバー（Jenkins等）を用意することなく、リポジトリ内の .github/workflows/ ディレクトリにYAML形式の設定ファイルを配置するだけで、コミットやプルリクエスト、ブランチマージをトリガーとした自動実行パイプラインを即座に構築できます。

### プルリクエストごとの自動品質チェックで防げる事故

チーム開発において、個々の開発者のローカル環境やスキルレベルに依存した手動検証には限界があります。「テストを実行し忘れてプッシュした」「フォーマッターの設定が異なり無駄な差分が大量に発生した」「型不一致による潜在的なバグがマージされた」といった事故は、日常的に発生しがちです。

GitHub Actionsを導入すると、開発者がプルリクエストを作成または更新するたびに、独立したクリーンな仮想マシン（Ubuntu等）上で以下の検証が自動実行されます：

1. 依存関係の整合性チェック: composer.lock に定義されたパッケージが正しくインストールできるかを検証します。
2. コードスタイルの自動検査: プロジェクトで定めたコーディング規約に違反していないかを瞬時に判定します。
3. 静的解析による型チェック: 実行時まで気付きにくい未定義メソッドの呼び出しやNull安全性の不備を検知します。
4. 自動テストの全件パス確認: 単体テスト・機能テスト（フィーチャーテスト）を実行し、既存機能のリグレッション（先祖返り）を防止します。

GitHubのブランチ保護ルール（Branch Protection Rules）と組み合わせることで、「CIの全チェックが成功するまで main ブランチへのマージを許可しない」という強制力を持たせることができ、本番ブランチの品質を常に担保できます。

また、ローカルでDockerを用いたコンテナ環境を構築しているチームも多いでしょう。Dockerコンテナでの開発環境構築については、[Laravel Sail解説ガイド](https://laravelwren.com/2026/08/21/laravel-sail-docker-guide/) で詳しく解説していますが、GitHub Actionsを活用することで、ローカルのDocker環境と同じPHP拡張モジュール・MySQLバージョンをクラウド上のCIランナー上に素早く再現し、環境差異による事故をゼロに近づけることが可能です。

### 開発サイクル短縮とリグレッションテストの省力化

自動化がもたらす最大の恩恵は、開発者の認知負荷と作業工数の大幅な削減です。

手動でテストやデプロイを行っている現場では、「リリース前に全テストを手元で回すのに10分以上かかる」「デプロイ担当者が手順書を見ながらSSHでサーバーに入り、コマンドを1つずつ叩く」といった非効率な運用が常態化しがちです。これらは作業自体のストレスだけでなく、リリース頻度の低下を招きます。

CI/CDを自動化することで、テストはクラウド上でバックグラウンド実行され、開発者はコードレビューや次の機能開発に専念できます。さらに、新機能の追加やリファクタリングを行っても、数分でリグレッションテストが完了するため、自信を持って高頻度なリリースサイクルを回せるようになります。

### CI/CDパイプラインの全体フロー比較早見表

LaravelにおけるCI（継続的インテグレーション）とCD（継続的デリバリー/デプロイ）の役割、実行トリガー、使用ツールを以下の比較表にまとめました。

このように、プルリクエスト段階では「CI（品質検査＋テスト）」によって欠陥の侵入を水際で防ぎ、mainブランチへのマージ完了時に「CD（自動デプロイ）」がキックされる二段構えのパイプラインを設計するのが実務のベストプラクティスです。

—

## 基本的なCIワークフローの構築（.github/workflows/ci.yml）

ここからは、Laravelプロジェクトの標準的なCIワークフローの構築手順を具体的に見ていきましょう。

まずはリポジトリのルートディレクトリに .github/workflows/ ディレクトリを作成し、その中に ci.yml を配置します。

“`yaml
# .github/workflows/ci.yml
name: Laravel CI

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

jobs:
laravel-ci:
name: Build & Test (PHP ${{ matrix.php-version }})
runs-on: ubuntu-latest
timeout-minutes: 15

strategy:
fail-fast: false
matrix:
php-version: [‘8.2’, ‘8.3’, ‘8.4’]

steps:
– name: リポジトリのチェックアウト
uses: actions/checkout@v4

– name: PHPおよび拡張モジュールのセットアップ
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-version }}
extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql, bcmath, fileinfo, zip, redis
coverage: none
tools: composer:v2

– name: Composerキャッシュディレクトリの取得
id: composer-cache
run: echo “dir=$(composer config cache-files-dir)” >> $GITHUB_OUTPUT

– name: Composer依存パッケージのキャッシュ
uses: actions/cache@v4
with:
path: ${{ steps.composer-cache.outputs.dir }}
key: ${{ runner.os }}-composer-${{ hashFiles(‘**/composer.lock’) }}
restore-keys: |
${{ runner.os }}-composer-

– name: Composerパッケージのインストール
run: composer install –no-interaction –prefer-dist –optimize-autoloader –no-progress

– name: CI用環境変数の準備
run: |
cp .env.example .env.ci
cp .env.ci .env
php artisan key:generate –env=ci

– name: 基本構文チェックとテスト実行
run: php artisan test
“`

### shivammathur/setup-php によるPHP・拡張モジュールのセットアップ

GitHub ActionsでPHPアプリケーションをビルド・テストする際のデファクトスタンダードが shivammathur/setup-php アクションです。

Laravelを安定して動作させるためには、PHP本体だけでなく必要な拡張モジュール（PHP Extensions）を確実に組み込む必要があります。

“`yaml
– name: PHPおよび拡張モジュールのセットアップ
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-version }}
extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql, bcmath, fileinfo, zip, redis
coverage: none
tools: composer:v2
“`

この設定の重要ポイントは以下の通りです：

* マトリックスビルドの活用: matrix.php-version を用いて PHP 8.2、8.3、8.4 などの複数バージョンで並行テストを実行できます。将来のPHPバージョンアップへの追従性を検証する上で極めて有効です。
* 必要十分な拡張モジュールの指定: Laravel 11/12系で必須となる mbstring, xml, pdo_mysql, bcmath, zip に加え、キューやキャッシュで頻繁に利用される redis をあらかじめ指定しておきます。
* コードカバレッジの無効化（高速化）: カバレッジ測定が不要な通常のCIでは coverage: none を指定します。XdebugやPCOVを無効化することで、テスト実行速度が2〜5倍程度高速化されます。

### Composer依存関係の効率的なキャッシュ設定（actions/cache）

CIパイプラインの実行時間において、大きな割合を占めるのが composer install による外部パッケージのダウンロード時間です。

毎回すべてのパッケージをPackagist等からダウンロードしていると、ネットワーク帯域の消費だけでなく、CIの待ち時間が長くなり開発テンポが阻害されます。公式の actions/cache@v4 を導入して依存関係をキャッシュしましょう。

“`yaml
– name: Composerキャッシュディレクトリの取得
id: composer-cache
run: echo “dir=$(composer config cache-files-dir)” >> $GITHUB_OUTPUT

#### キャッシュの仕組みと注意点
1. キャッシュキーの設計: composer.lock のハッシュ値（hashFiles('**/composer.lock')）をキーに含めることで、依存関係が変更されたときのみ新規にキャッシュが生成され、パッケージ構成が変わらない限り既存キャッシュが高速に復元されます。
2. ベンダーディレクトリ（vendor/）ではなくダウンロードキャッシュを保存: vendor/ ディレクトリ自体をキャッシュすると、オートローダーの不整合やOS固有のバイナリパッケージでトラブルが起きやすくなります。Composer公式が推奨するキャッシュディレクトリ（cache-files-dir）をキャッシュ対象とするのが最も安全で堅牢です。

### 環境変数ファイル（.env.ci）とAPP_KEYの準備

Laravelアプリケーションは、暗号化やセッション管理のために APP_KEY を必要とします。リポジトリにコミットされている .env.example には有効な APP_KEY が含まれていないため、CI環境でそのまま php artisan test を実行すると、「No application encryption key has been specified.」というエラーでジョブが停止してしまいます。

CI環境で安全に環境変数を準備するパターンは主に2つあります：

#### パターンA：ワークフロー内で動的にキーを生成（手軽で一般的）
“`bash
cp .env.example .env
php artisan key:generate
“`
テストごとに新しい一時キーを発行するため、シークレットの設定漏れがなく手軽に運用できます。

#### パターンB：固定のCI専用キーと設定（推奨）
リポジトリ内にテスト専用の設定ファイル .env.ci を作成し、あらかじめテスト用の設定（SQLiteインメモリ設定、ダミーのAPP_KEY等）を記述しておく手法です。

“`dotenv
# .env.ci
APP_NAME=Laravel-CI
APP_ENV=testing
APP_KEY=base64:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
APP_DEBUG=true
APP_URL=http://localhost

LOG_CHANNEL=stderr

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_test
DB_USERNAME=root
DB_PASSWORD=root_password

CACHE_STORE=array
QUEUE_CONNECTION=sync
SESSION_DRIVER=array
“`

この .env.ci をコミットしておき、CIジョブ内で cp .env.ci .env としてコピーすることで、環境変数の一貫性が保たれ、意図しない外部サービスへのリクエスト送信や設定漏れを確実に防ぐことができます。

—

## データベースを利用したテストの自動実行

実際のLaravelアプリケーション開発では、インメモリのSQLiteだけでは不十分なケースが多々あります。「MySQL特有のJSON関数やFULLTEXTインデックスを使用している」「ストアドプロシージャや外部キー制約の挙動を検証したい」「Redisを用いたセッション・キャッシュの整合性を担保したい」といった場合、本番環境と同一系統のデータベースエンジンを用いた結合テストが不可欠です。

GitHub Actionsには、ジョブ実行時にDockerコンテナを自動で起動・破棄できる サービスコンテナ（Service Containers） 機能が備わっています。

### GitHub Actionsのサービスコンテナ（MySQL / PostgreSQL / Redis）設定

以下は、CIランナー上でMySQL 8.0とRedisのコンテナを立ち上げ、Laravelから安全に接続するためのワークフロー設定例です。

“`yaml
jobs:
test-database:
name: Database Feature Test
runs-on: ubuntu-latest
timeout-minutes: 15

# サービスコンテナの定義
services:
mysql:
image: mysql:8.0
env:
MYSQL_ROOT_PASSWORD: root_password
MYSQL_DATABASE: laravel_test
ports:
– 3306:3306
options: >-
–health-cmd=”mysqladmin ping -h localhost –silent”
–health-interval=10s
–health-timeout=5s
–health-retries=5

redis:
image: redis:alpine
ports:
– 6379:6379
options: >-
–health-cmd=”redis-cli ping”
–health-interval=10s
–health-timeout=5s
–health-retries=5

steps:
– name: リポジトリのチェックアウト
uses: actions/checkout@v4

– name: PHP環境のセットアップ
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.3’
extensions: mbstring, pdo_mysql, redis, bcmath, zip
coverage: none

– name: Composerキャッシュとパッケージインストール
run: |
composer install –no-interaction –prefer-dist –optimize-autoloader

– name: 環境変数ファイルの配置
run: cp .env.ci .env

– name: マイグレーションの実行
env:
DB_CONNECTION: mysql
DB_HOST: 127.0.0.1
DB_PORT: 3306
DB_DATABASE: laravel_test
DB_USERNAME: root
DB_PASSWORD: root_password
run: php artisan migrate –force

– name: Pest並列テストの実行
env:
DB_CONNECTION: mysql
DB_HOST: 127.0.0.1
DB_PORT: 3306
DB_DATABASE: laravel_test
DB_USERNAME: root
DB_PASSWORD: root_password
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
run: php artisan test –parallel –recreate-databases
“`

#### サービスコンテナ設定の重要ポイント
1. ヘルスチェック（–health-cmd）の必須設定: MySQLコンテナは起動コマンドが実行されてから実際にクエリを受け付ける状態になるまで数秒〜数十秒の時間を要します。ヘルスチェックを設定しないと、マイグレーションステップが「Connection refused」で即座に失敗します。--health-retries=5 を指定して確実に接続待機を行いましょう。
2. ホスト名の解決: サービスコンテナのポートをホストにマッピング（3306:3306）しているため、PHP側からは 127.0.0.1 宛てに接続します（localhost ではUnixドメインソケットを探しにいってしまう場合があるため、明示的に 127.0.0.1 を指定するのが鉄則です）。

### マイグレーション実行とPest / PHPUnitでのテスト並列実行（–parallel）

テストケースが数十から数百件に増えてくると、直列実行では数分から十数分かかるようになり、CIの待ち時間が開発者の大きなストレスになります。

モダンなLaravel開発では、簡潔な記法と圧倒的な表現力を持つテスティングフレームワーク Pest の採用が急速に進んでいます。テストコードの書き方や基本概念については、[Laravel Pestテスト入門ガイド](https://laravelwren.com/2026/08/21/laravel-pest-testing-guide/) で基礎から実践まで網羅していますが、GitHub Actions上では 並列テスト実行（--parallel） オプションを活用することで、実行時間を最大で数分の一に短縮できます。

“`bash
php artisan test –parallel –recreate-databases
“`

#### 並列テスト実行時のデータベース分離の仕組み
* --parallel を指定すると、Laravelは runner のCPUコア数に応じた並列ワーカープロセス（laravel_test_test_1, laravel_test_test_2 等）を立ち上げます。
* 各ワーカーは独立した個別データベースを作成・参照するため、テストデータが相互に干渉（データ競合）する心配がありません。
* 初回実行時やスキーマ変更時は --recreate-databases を付与することで、各テスト用DBの再構築を安全に行えます。

### テスト実行の高速化テクニックとDBキャッシュ最適化

CIの実行時間を極限まで削るための実践的な高速化テクニックをいくつか紹介します。

1. Bcryptのハッシュコスト削減:
ユーザー認証を含むテストでは、パスワードハッシュ（Hash::make()）の計算に多くのCPU時間を消費します。テスト環境用の設定（phpunit.xml または .env.ci）でハッシュ計算コストを最小値に設定することで、認証テストの速度が劇的に向上します。
“`xml

“`
2. スキーマダンプ（schema:dump）の活用:
マイグレーションファイルの数が数十〜数百に達している歴史のあるプロジェクトでは、migrate に数十秒以上かかることがあります。php artisan schema:dump を用いて単一のSQLファイルにまとめておくことで、マイグレーション実行時間を大幅に短縮できます。
3. 外部HTTPリクエストのモック（Http::fake()）:
決済APIや外部外部SaaS連携のテストで実リクエストが飛ぶと、テスト速度が極端に低下するだけでなく、外部のネットワーク障害でCIが不定期に落ちる原因になります。必ず Http::fake() を用いてレスポンスをモック化しましょう。

—

## コード品質を高める静的解析とコードフォーマットの自動化

テストコードの実行だけでなく、コードの「可読性」と「型安全性」を機械的に担保する仕組みをCIに組み込むことで、プルリクエストのレビュー工数を大幅に削減できます。

Laravelエコシステムには、ゼロコンフィグで美しいコードスタイルを実現する Laravel Pint と、強力な型推論を提供する Larastan（PHPStan） が用意されています。

### Laravel Pintによる構文チェックと自動コミット/PRコメント

Laravel Pintは、PHP-CS-FixerをベースにLaravel向けに最適化された opinionated なコードスタイルフォーマッターです。インデント、配列の改行、不要なインポート文の整理などを自動で行ってくれます。

詳細な導入手順やルールカスタマイズについては、[Laravel Pintコードスタイル統一ガイド](https://laravelwren.com/2025/08/02/laravel-pint/) を参照してください。

GitHub Actionsでは、以下の2通りのアプローチでPintを運用できます。

#### アプローチ1：スタイル違反があったらCIを失敗させる（推奨・最もクリーン）
“`yaml
– name: Laravel Pintによるコードスタイル検査
run: vendor/bin/pint –test
“`
--test オプションを付与すると、スタイル規約違反が1箇所でもあれば終了コード 1 を返し、CIジョブをエラーとして終了させます。開発者は手元で vendor/bin/pint を実行して再プッシュすることを促されます。

#### アプローチ2：Pintで自動修正し、CIからプルリクエストへ自動コミットする
開発者の手元修正の手間を省くため、CIランナー上でPintを実行し、変更があれば自動でブランチにコミットをプッシュバックする設定も可能です。

“`yaml
– name: Laravel Pintによる自動コード整形
run: vendor/bin/pint

– name: 整形結果の自動コミット
uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: “style: Laravel Pintによるコード自動整形 [skip ci]”
branch: ${{ github.head_ref }}
“`
※ [skip ci] をコミットメッセージに含めることで、自動コミットによってCIが無限ループで再トリガーされる事態を防止できます。

### Larastan（PHPStan）による型チェックと潜在バグ検出

PHPは動的型付け言語ですが、PHP 8系以降の型宣言の強化に伴い、静的解析ツールによる型検査が不可欠になっています。

Larastan は、静的解析ツールである PHPStan に Laravel 特有のマジックメソッドや Eloquent リレーション、ファサードの動的解決ルールを追加した公式推奨ライブラリです。

“`bash
composer require –dev “larastan/larastan”
“`

プロジェクトルートに phpstan.neon を作成します。

“`neon
# phpstan.neon
includes:
– vendor/larastan/larastan/extension.neon

parameters:
paths:
– app/
– bootstrap/
– config/
– database/
– routes/
– tests/

# レベル0（最も寛容）からレベル9（最も厳格）まで設定可能
# 実務ではまずレベル5〜6を目指すのが現実的
level: 6

checkMissingIterableValueType: false
“`

GitHub Actionsのワークフローに以下のステップを追加します：

“`yaml
– name: Larastan（PHPStan）による静的解析
run: vendor/bin/phpstan analyse –error-format=github –no-progress
“`

--error-format=github を指定すると、GitHubのプルリクエスト画面の差分ビュー（Files changed）上に、エラー発生行がインラインアノテーション（警告・エラー注記）として直接表示されるため、レビュー担当者や作成者が該当箇所を一目で把握できます。

### コミット前フック（Git Hook）との違いとCIでの強制力

ローカル環境で Husky や Git pre-commit フックを用いて Pint や PHPStan を実行しているチームも多いでしょう。

しかし、ローカルフックは以下の理由から「万全」ではありません：
* 開発者が git commit --no-verify オプションで意図的・偶発的にスキップできる。
* 新しくチームに参画したメンバーがローカルフックのセットアップを忘れる可能性がある。
* 実行マシンのPHPバージョンやComposerパッケージのバージョン差異により、手元では通ったチェックが他環境で落ちる。

ローカルフックは「手元での早期フィードバック」として有用ですが、プロジェクトの品質を守る 絶対的な最終防衛ライン（品質ゲート） として機能するのは、クラウド上で厳格に実行される GitHub Actions のCIワークフローです。

—

## GitHub Actionsによる本番/ステージング環境への自動デプロイ設計

CIによってコードの品質とテスト通過が保証されたら、次は 本番・ステージング環境への自動デプロイ（CD） です。

手動でのSSHログインやFTPアップロードを廃止し、GitHub Actions経由で自動デプロイを完結させることで、リリース作業に伴う人為的ミスを完全に排除できます。

### GitHub Secretsを用いた安全なSSH接続と鍵管理

サーバーへ安全にコマンドを送信するために、SSH秘密鍵や接続情報をGitHubリポジトリの Settings > Secrets and variables > Actions に暗号化して登録します。

#### 登録すべき必須シークレット一覧
* SSH_PRIVATE_KEY: デプロイ専用ユーザーのSSH秘密鍵（パスフレーズなし）
* SERVER_HOST: デプロイ先サーバーのIPアドレスまたはホスト名
* SERVER_USER: デプロイを実行するLinuxユーザー名（例: deployer, www-data）
* SERVER_PORT: SSHポート番号（デフォルトの22以外に変更している場合）

#### SSHキーペア作成時のセキュリティ留意点
1. デプロイ専用の鍵を生成: 個人用のSSHキーを使い回さず、ssh-keygen -t ed25519 -C "github-actions-deploy" でデプロイ専用のキーペアを作成します。
2. 最小権限の原則: サーバー側で root ユーザーを直接ログインさせず、Webルート配下のみ書き込み権限を持つ専用ユーザー（deployer など）を作成し、その ~/.ssh/authorized_keys に公開鍵を登録します。

### Artisan最適化コマンド（config:cache, route:cache, view:cache）の自動実行

本番環境のLaravelアプリケーションでは、リクエストごとの設定ファイル読み込みやルート解決のオーバーヘッドを削減するため、Artisanのキャッシュ作成コマンドを実行することがパフォーマンス向上の必須要件です。

デプロイ時に実行すべき最適化コマンドの順序は以下の通りです：

“`bash
# 1. メンテナンスモードの有効化（ダウンタイムが許容される場合）
php artisan down –retry=60 –secret=”emergency-access-token”

# 2. マイグレーションの実行
php artisan migrate –force

# 3. 以前のキャッシュをクリア
php artisan optimize:clear

# 4. 新しい設定・ルート・ビューのキャッシュを一括生成
php artisan optimize
php artisan view:cache
php artisan event:cache

# 5. キューワーカープロセスの再起動（新しいコードを反映させるため必須）
php artisan queue:restart

# 6. メンテナンスモードの解除
php artisan up
“`

#### なぜ `queue:restart` が必須なのか
Laravelのキューワーカー（Supervisor等で常駐している php artisan queue:work プロセス）は、起動時のPHPコードをメモリ上に保持し続けます。デプロイによって新しいコードが配置されても、プロセスを再起動しない限り古いコードのままジョブを処理し続け、予期せぬ不整合やバグの原因になります。デプロイの末尾で必ず php artisan queue:restart を発行しましょう。

### Deployerまたはゼロダウンタイムデプロイの連携フロー

単純に git pull を行う方式では、パッケージのインストール中やマイグレーション中に一時的なファイル不整合が発生し、アクセスしたユーザーに「500 Internal Server Error」が表示されるリスクがあります。

これを防ぐのが シンボリックリンク切り替え方式（ゼロダウンタイムデプロイ） です。PHPエコシステムで最も実績のあるデプロイツールが Deployer です。

#### Deployerのディレクトリ構造
“`text
/var/www/my-app/
├── current -> releases/3/ # 現在公開中の最新バージョン（シンボリックリンク）
├── releases/
│ ├── 1/
│ ├── 2/
│ └── 3/ # デプロイ完了時に atomic に切り替え
├── shared/ # 各リリース間で永続化・共有するファイル
│ ├── .env
│ └── storage/
“`

GitHub ActionsからDeployerを実行するか、あるいは軽量なSSHアクション（appleboy/ssh-action）を用いて同等のリリースフローを実行します。

以下に、実務で即座にコピペして運用できる自動デプロイワークフロー全文を提示します。

“`yaml
# .github/workflows/deploy.yml
name: Deploy to Production

on:
push:
branches:
– main

concurrency:
group: production-deploy
cancel-in-progress: false

jobs:
# CIテストが完全に通過していることを確認
test:
name: Run Tests Prior to Deploy
uses: ./.github/workflows/ci.yml

deploy:
name: Execute Production Deployment
needs: [test]
runs-on: ubuntu-latest
timeout-minutes: 20

steps:
– name: リポジトリのチェックアウト
uses: actions/checkout@v4

– name: SSH経由での本番サーバーデプロイ実行
uses: appleboy/ssh-action@v1.0.3
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
port: ${{ secrets.SERVER_PORT || 22 }}
script_stop: true
script: |
set -e

echo “=== デプロイ処理を開始します ===”
cd /var/www/my-app

# 1. メンテナンスモード有効化（バイパス用シークレットキー付き）
php artisan down –render=”errors::503″ –secret=”${{ secrets.DEPLOY_BYPASS_SECRET }}” || true

# 2. 最新コードの取得
git fetch origin main
git reset –hard origin/main

# 3. 本番用Composerパッケージのインストール（dev用は除外）
composer install –no-dev –no-interaction –prefer-dist –optimize-autoloader

# 4. フロントエンドアセットのビルド（必要な場合）
# npm ci && npm run build

# 5. マイグレーションの実行
php artisan migrate –force

# 6. アプリケーション最適化キャッシュの生成
php artisan optimize:clear
php artisan optimize
php artisan view:cache
php artisan event:cache

# 7. キューワーカーおよびキャッシュエンジンのリフレッシュ
php artisan queue:restart

# 8. メンテナンスモード解除
php artisan up

echo “=== デプロイが正常に完了しました ===”
“`

#### 設定のポイント
* concurrency設定: 複数のコミットが連続してプッシュされた際、デプロイジョブが並列で重複実行されると競合を起こします。concurrency を設定して直列実行を強制します。
* needs: [test]: テストジョブが成功しない限りデプロイジョブが起動しない依存関係を設定しています。
* script_stop: true: スクリプト内のいずれかのコマンドが失敗した時点でSSHセッションを即時中断し、不完全な状態でのリリースを防ぎます。

—

## 実務でよく遭遇するトラブルと解決策（FAQ）

GitHub Actionsを実際の運用環境に組み込む際、多くのエンジニアが一度は突き当たる代表的なトラブルとその回避策をまとめました。

### Composerパッケージのメモリ不足・タイムアウト対策

CI環境で composer install や composer update を実行した際、以下のような致命的エラーでジョブが異常終了することがあります：

“`text
Fatal error: Allowed memory size of 1610612736 bytes exhausted (tried to allocate 32768 bytes)
“`

これは、Composerの依存解決アルゴリズムが消費するメモリ量が、PHPのデフォルト設定（memory_limit）の上限値を超えてしまうために発生します。

#### 回避策：COMPOSER_MEMORY_LIMIT=-1 の明示指定
ワークフローのステップ環境変数として COMPOSER_MEMORY_LIMIT=-1 を付与することで、一時的にメモリ制限を解除してプロセスを完走させることができます。

“`yaml
– name: Composerパッケージのインストール（メモリ上限解除）
env:
COMPOSER_MEMORY_LIMIT: -1
run: composer install –no-interaction –prefer-dist –optimize-autoloader
“`

また、composer update は実行時に膨大なメモリとCPUを消費するため、CI環境上で実行するのは厳禁です。ローカルで依存解決を行い、生成された composer.lock をコミットした上で、CI環境では常に composer install のみを行うのが鉄則です。

### DBマイグレーション失敗時のロールバックと通知設計（Slack/Discord連携）

自動デプロイ中に最も警戒すべき事態が、「マイグレーション（php artisan migrate --force）の途中でSQLエラーが発生し、処理が中断すること」です。

このとき、メンテナンスモードが解除されないまま放置されたり、どのステップで失敗したのかチームが気付けないと、障害の初動対応が遅れてしまいます。

#### 1. エラーハンドリングと自動復旧（trap構文）
シェルスクリプトの trap 構文を活用し、デプロイスクリプトが異常終了した場合でも必ずメンテナンスモードを解除するか、エラー状態を記録するセーフティネットを仕込んでおきます。

“`bash
# エラー発生時に必ず実行される関数を登録
trap ‘echo “デプロイ中に重大なエラーが発生しました。状態を確認してください。”; php artisan up; exit 1’ ERR
“`

#### 2. Slack / Discord へのリアルタイム通知連携
ビルドやデプロイの成功・失敗をチャットツールに即座に通知することで、開発チーム全体がデプロイ状況を可視化できます。

“`yaml
– name: デプロイ結果のSlack通知
if: always()
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
fields: repo,message,commit,author,action,eventName,ref,workflow
env:
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
“`
if: always() を指定することで、途中のステップでエラーが発生した場合でも、確実に失敗通知がSlackチャンネルへ届きます。

### GitHub Actionsの実行時間制限（クォータ）の節約テクニック

プライベートリポジトリにおけるGitHub Actionsの無料枠（月間2,000分等）は、コミット頻度の高いアクティブな開発現場ではすぐに上限に達してしまいます。無駄なビルドコストを抑える工夫を取り入れましょう。

1. 特定ファイルの変更時のみジョブを実行する（pathsフィルタ）:
ドキュメント（README.md や docs/）の更新、フロントエンドのみの変更時にPHPのテストを回す必要はありません。paths-ignore を設定して不要なジョブ実行をスキップします。
“`yaml
on:
push:
paths-ignore:
– ‘**.md’
– ‘docs/**’
– ‘.gitignore’
“`
2. 先行ジョブの自動キャンセル（concurrency）:
同一のプルリクエストに短時間で連続コミットがプッシュされた場合、古いコミットに対するCIジョブを実行し続けるのは実行時間の無駄です。cancel-in-progress: true を設定すると、最新コミットがプッシュされた時点で古い実行中ジョブが自動停止します。
“`yaml
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
“`
3. タイムアウトの明示的指定:
万が一ジョブが無限ループやデッドロックに陥った際、GitHub Actionsのデフォルトタイムアウト（最大360分＝6時間）までランナーを占有してしまうリスクがあります。各ジョブに必ず timeout-minutes: 10〜15 程度を設定しておきましょう。

—

## まとめ：堅牢なCI/CDパイプラインでLaravel開発の生産性を最大化する

本記事では、LaravelアプリケーションにおいてGitHub Actionsを用いた高品質かつ堅牢なCI/CDパイプラインを構築する全手順を解説しました。

### CI/CD導入チェックリスト

パイプラインを本番運用に乗せる前に、以下の項目が正しく設定されているかセルフチェックを行ってみてください。

* [ ] shivammathur/setup-php で必要なPHP拡張モジュール（pdo_mysql, redis, bcmath 等）が網羅されている
* [ ] actions/cache によって composer config cache-files-dir が適切にキャッシュされている
* [ ] テスト環境用の .env.ci または動的な APP_KEY 発行が行われている
* [ ] MySQLやRedisのサービスコンテナに適切なヘルスチェック（--health-cmd）が設定されている
* [ ] PestまたはPHPUnitで並列実行（--parallel）が設定され、テスト時間が短縮されている
* [ ] Laravel Pint によるコードスタイル検査がCIで自動検証されている
* [ ] Larastan（PHPStan）による型安全性チェックが導入されている
* [ ] GitHubのブランチ保護ルールで、CIパスをマージ必須条件に設定している
* [ ] SSH秘密鍵やサーバー情報が GitHub Secrets に安全に登録されている
* [ ] デプロイフローに php artisan optimize および php artisan queue:restart が組み込まれている
* [ ] 失敗時のエラー通知（Slack / Discord）が設定されている

### 段階的な導入ステップ（テスト自動化から自動デプロイまで）

最初から完璧な自動デプロイまでを一度に組み込もうとすると、設定項目が多く挫折しがちです。まずは以下のロードマップに沿って段階的にパイプラインを育てることをおすすめします。

1. ステップ1（品質ゲートの確立）: まずは Laravel Pint のスタイルチェックと Larastan の型解析だけをプルリクエストで自動実行する。
2. ステップ2（自動テストの導入）: サービスコンテナを立ち上げ、php artisan test --parallel によるPest/PHPUnitテストをCIで回す。
3. ステップ3（ステージング環境への自動デプロイ）: developブランチへのマージを契機に、検証用ステージングサーバーへ自動反映させる。
4. ステップ4（本番環境の安全な自動リリース）: mainブランチへのタグ発行や承認フローをトリガーとして、本番環境へのゼロダウンタイム自動デプロイを実現する。

自動化されたCI/CDパイプラインは、開発者の手作業による不安を払拭し、新機能の価値をユーザーへ最速で届けるための最も強力な武器となります。ぜひ本ガイドを参考に、チームに最適なパイプラインを構築してみてください。

関連記事

コメント