🤗

GitLab から始める CI/CD の基本（Laravel × Azure / AWS 編）

に公開
Laravel
GitLab
CI/CD
Elastic Beanstalk
Azure App Service
tech

GitLab から始める CI/CD の基本

Azure App Service（コード） / AWS Elastic Beanstalk 編（Laravel アプリ）

はじめに

近年、アプリケーション開発において CI/CD の自動化 は欠かせない存在です。
特に、独自ドメインで運用する GitLab を使っている現場では、外部 SaaS に依存しないセキュリティ面の利点や、柔軟なカスタマイズが魅力です（本記事でも独自ドメイン構成の GitLab を使用しています）。

本記事では、Laravel アプリをデプロイするケース を例に、

  • Azure App Service（コード方式）
  • AWS Elastic Beanstalk

という 2 つの方式を想定した GitLab 側の準備 にフォーカスして解説します。

本記事で扱う前提環境（筆者の構成）

項目 内容
GitLab 独自ドメインでホストされた GitLab（セルフホスティング）
Runner Windows 環境（PowerShell 実行）で登録
対象アプリ Laravel アプリケーション
デプロイ方式 ZIP デプロイ（Azure App Service / AWS EB）
コンテナ方式 本記事では 扱わない（利用経験あり)

GitLab Runner とは？ なぜ必要？

GitLab では、CI/CD のジョブ（ビルド・テスト・デプロイなど）は GitLab Runner という仕組みで実行されます。

Runner がないと動かない

  • .gitlab-ci.yml に書いたスクリプトは GitLab 自体が直接実行するわけではない
  • Runner という「作業を代行するロボット」に命令を送って、ビルドやデプロイを実行する仕組み

Runner 設定画面

GitLab の Settings > CI/CD から、Runner の設定や登録状況を確認できます。
Variables（環境変数）の登録も同じ画面から行います。

GitLab Runner と Variables の設定画面

この画面の Runners で Runner の登録・接続状況を確認し、
Variables でクラウドの認証情報などを安全に管理します。

Runner の種類と環境の違い

GitLab Runner はどこで動かすかによってコマンドや設定が変わります。

実行環境 備考
Linux (Bash) サーバー運用が多い現場で使われる。Docker executor が人気
Windows (PowerShell) Windows 環境や IIS 運用の現場で使うことも
macOS 少数派だけど開発用に使うことも

例えば同じ「echo」でも、PowerShell なら Write-Output、Linux なら echo を使うなど細かい違いがあります。

Runner が必要になる理由

クラウド PaaS にデプロイする場合でも、以下の処理を GitLab Runner が実行 します。

  • Azure CLI / AWS CLI などのコマンド実行
  • ソースコードのビルド
  • Laravel の composer install、npm install など
  • Docker build / push
  • 環境変数の受け取り

シークレット管理

Laravel アプリをクラウドにデプロイするには、GitLab 側で以下のような「認証情報」を安全に保持する必要があります。

🔐 登録が必要な変数の例

用途 変数の例
Azure 認証情報 AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID
AWS 認証情報 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
App Service 設定 AZURE_RG, AZURE_APP_NAME
コンテナ方式（ACR 認証など） AZURE_CR_USERNAME, AZURE_CR_PASSWORD（PAT または SP 認証）

※ Laravel アプリの APP_KEY, DB_HOST などの アプリ固有の環境変数はクラウド側で管理するのが基本です。GitLab に登録する必要はありません。

💡 GitLab 上での登録方法

GitLab の Settings → CI/CD → Variables 画面から追加できます。
Protect や Mask を有効にすることで、安全に利用できます。
※gitlabのプランによってはMaskは不可なこともあります

.gitlab-ci.yml の基本と設置場所

GitLab CI/CD の構成は、リポジトリ直下に置かれる .gitlab-ci.yml ファイルに定義します。
このファイルがあることで、GitLab はリポジトリに対して CI/CD を自動で実行できるようになります。

your-laravel-project/
├── app/
├── config/
├── routes/
├── .gitignore
├── composer.json
├── .gitlab-ci.yml  ← ここに置く

.gitlab-ci.yml に書くこと

このファイルには、以下のような内容を定義します：

  • stages: ビルドやデプロイなどの段階（例：build → deploy）
  • 各ステージごとの script: 実際に実行するコマンド
  • only や rules: どのブランチで実行するかなどの条件
  • artifacts: 出力ファイルの保存指定（例：ビルド成果物の ZIP）

補足：ファイル命名と場所は厳格

  • ファイル名は必ず .gitlab-ci.yml
  • ルート直下に置くことが基本

これを間違えると GitLab が CI を認識できないので注意が必要です。

ZIP デプロイ型：App Service（コード） & AWS Elastic Beanstalk の共通構成

はじめに

Laravel アプリをクラウドにデプロイする際、
「ZIP 形式でアップロードするコードデプロイ方式」は、比較的シンプルで扱いやすい方法です。

本記事では以下の2つを対象に、GitLab CI/CD からの構成を共通化しつつ解説します。

  • Azure App Service（コード方式）
  • AWS Elastic Beanstalk

ZIP デプロイに向けた事前準備（Azure / AWS）

GitLab CI/CD からデプロイする前に、各クラウドで最低限の準備を済ませておく必要があります。
ここでは、Azure App Service（コード方式）と AWS Elastic Beanstalk を対象に、それぞれの 初期構築でやっておくことを簡単に整理します。

✅ Azure App Service（コード方式）の事前準備

  • App Service（コード方式）を作成（PHP ランタイムなどを選択）
  • リソースグループ（RG）名や App Service 名を控えておく
  • 必要に応じて、App Service 側でアプリの環境変数（APP_KEY など）を登録

Azure CLI を使って各種情報を取得できます：

az webapp list --output table
az webapp config appsettings list --name <APP_NAME> --resource-group <RESOURCE_GROUP>

🔐 サービスプリンシパルで取得する認証情報

Azure CLI を使ってサービスプリンシパルを作成すると、以下の情報が取得できます：

  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_TENANT_ID
  • AZURE_SUBSCRIPTION_ID（必要に応じて）

これらは GitLab の CI/CD Variables に登録しておくことで、必要に応じて Azure CLI での認証処理（az login）などに利用できます。

✅ AWS Elastic Beanstalk（ZIP方式）の事前準備

  • Elastic Beanstalk アプリケーションを作成（プラットフォーム：PHP）
  • EB 環境（EC2 など）を作成（S3 バケットも用意しておく）
  • アプリ側で特殊な設定が必要な場合、.ebextensions/ ディレクトリを用意しておく（必要に応じて）

.ebextensions/ は YAML 形式の設定ファイル群を置く特殊ディレクトリで、
EC2 のインスタンス構成・環境変数・パッケージ追加などが定義できます。

このように、Azure / AWS でやるべき事前準備は異なりますが、
以降の GitLab CI/CD の構成はかなり共通化できます。

共通の CI/CD フロー

両者ともに、GitLab CI での構成は以下のように非常に似ています。

✅ ステージ構成

stages:
  - build
  - deploy

✅ ビルドステージ（共通）

※ この例では、必要に応じた各種ツールが実行環境にインストール済みであることを前提としています。
実行コマンドは PowerShell を想定していますが、環境に応じて適宜読み替えてください。

build:
  stage: build
  script:
    # Laravel の依存パッケージをインストール
    - composer install --no-dev --optimize-autoloader
    - npm install
    - npm run build

    # デプロイ用フォルダ作成
    - New-Item -ItemType Directory -Force -Path publish

    # 必要ファイルをコピー
    - Copy-Item -Recurse -Force app publish\app
    - Copy-Item -Recurse -Force config publish\config
    # （中略：resources, routes, vendor, artisan などを publish 配下へコピー）
    - ...

    # ZIP作成
    - Compress-Archive -Path publish\* -DestinationPath app.zip

  artifacts:
    paths:
      - app.zip

✅ デプロイステージ（クラウドによって差異あり）

Azure App Service（コード方式）

※ この例では、必要に応じた各種ツールが実行環境にインストール済みであることを前提としています。
実行コマンドは PowerShell を想定していますが、環境に応じて適宜読み替えてください。

deploy:
  stage: deploy
  script:
    # 環境変数を使って Azure にログイン（サービスプリンシパル認証）
  - az login --service-principal `
      --username=$env:ARM_CLIENT_ID `
      --password=$env:ARM_CLIENT_SECRET `
      --tenant=$env:ARM_TENANT_ID

  # 対象のサブスクリプションを選択
  - az account set --subscription $env:ARM_SUBSCRIPTION_ID

  # App Service に ZIP デプロイを実行
  - az webapp deployment source config-zip `
      --resource-group $env:AZURE_RESOURCE_GROUP `
      --name $env:AZURE_APP_NAME `
      --src $env:ZIP_NAME
  only:
    # main ブランチのときだけこのジョブを実行（develop や feature ブランチでは無視される）
    - main
AWS Elastic Beanstalk

※ この例では、必要に応じた各種ツールが実行環境にインストール済みであることを前提としています。
実行コマンドは PowerShell を想定していますが、環境に応じて適宜読み替えてください。

deploy:
  stage: deploy
  script:
     # ZIP ファイルを S3 バケットにアップロード
  - pwsh -Command "aws s3 cp app.zip s3://$env:S3_BUCKET_NAME/app.zip"

  # EB アプリケーションの新バージョンを作成
  - pwsh -Command "aws elasticbeanstalk create-application-version `
      --application-name $env:EB_APPLICATION_NAME `
      --version-label $env:CI_COMMIT_SHA `
      --source-bundle S3Bucket=$env:S3_BUCKET_NAME,S3Key=app.zip"

  # EB 環境を新しいバージョンに更新
  - pwsh -Command "aws elasticbeanstalk update-environment `
      --environment-name $env:EB_ENVIRONMENT_NAME `
      --version-label $env:CI_COMMIT_SHA"
  only:
    # main ブランチのときだけこのジョブを実行（develop や feature ブランチでは無視される）
    - main

✅ Protected Branches の設定（GitLab）

GitLab では、CI/CD の安全性を高めるために Protected Branches（保護ブランチ） の仕組みがあります。
CI/CD を only: main などで制御する場合や、機密性の高い環境変数（Variables） を使う場合は、
対象のブランチを "Protected" に設定しておく必要があります。

🔒 なぜ保護が必要？

  • GitLab の環境変数には「保護された変数（Protected Variables）」があります。
  • これらの変数は Protected ブランチ上のジョブでしか参照されません。
  • つまり、main や release など、保護ブランチに対してのみ有効となります。

⚙ 設定画面の場所

  1. GitLab のリポジトリを開く
  2. メニューから Settings > Repository を選択
  3. Protected Branches セクションを開く

Protected Branches 設定画面

上記のように「Protected Branches」設定画面から、main ブランチなどを指定し、
誰が push / merge / deploy できるかを制御できます。

✅ .gitlab-ci.yml との関連

以下のように .gitlab-ci.yml 内で only: main と指定する場合、
main ブランチを Protected にしておかないと CI が正しく動かない ことがあります：

only:
  - main # main ブランチのみで CI/CD を実行

また、環境変数（たとえばクラウド認証用の AZURE_CLIENT_SECRET など）を GitLab に登録している場合、
それが Protected に設定されていると、Protected ブランチでしか使われないため注意が必要です。

💡 補足：Variables も合わせて確認を

  • GitLab の Settings > CI/CD > Variables から変数を登録可能
  • 環境変数を "Protected" にすると、Protected Branches でしか有効になりません
  • ブランチが Protected でなければ、CI ジョブが変数を取得できずエラーになります
ERROR: Missing required variable: AZURE_CLIENT_SECRET

GitLab の Pipelines 実行状況を確認する

GitLab のメニューから CI / CD → Pipelines を開くと、
CI/CD の実行履歴や結果を確認できます。

✅ Pipelines 画面の各列の意味

項目 説明
Status 実行結果（passed, failed, canceled など）
Pipeline 実行履歴のリンク。latest ラベルがついていれば最新実行
Commit 該当のコミットメッセージとリンク
Stages .gitlab-ci.yml で定義した各ステージの実行状態（✔ や ⭕ など）

🔁 latest ラベルとは？

同じブランチで直近に実行された Pipeline に自動で付与されます。
再実行時や最新の成功・失敗確認に便利です。

📄 ログの確認方法

✔ / ❌ マークのステージ名をクリックすると、
そのジョブの 実行ログ（コマンドの標準出力など） が表示されます。

  • composer install の進行状況
  • npm run build のログ
  • Azure / AWS CLI 実行結果
    など、トラブル発生時の原因調査に役立ちます。

✅ CI/CD 成功の確認ポイント（最終チェック）

CI/CD の構成が正しく動作していれば、GitLab 上およびデプロイ先クラウド上で以下の状態が確認できます。

🧪 GitLab Pipelines の確認

  • Pipelines のステージがすべて passed（✔）になっている
  • 各ステージのログを確認し、エラーがなく最後まで実行されている

☁ デプロイ先クラウド（Azure / AWS）側の確認

以下のような 所定のディレクトリに ZIP 展開されたソースコードが存在していれば、CI/CD は成功とみなせます。

クラウド 展開先パス 備考
Azure App Service（コード方式） /home/site/wwwroot artisan, vendor/ などが確認できれば OK
AWS Elastic Beanstalk（PHP Platform） /var/app/current 同様に Laravel アプリのソース構成が展開されていれば OK

※ 実際には Azure Portal の「SSH」や EB の EC2 に接続して確認できます。

📄 ログ・イベントによる確認

  • Azure: Log Stream や 診断ログ にエラーがないか確認
  • AWS: EB の「イベント」「ログ」タブでアプリの展開・起動に成功しているかを確認

✅ ここまで確認できれば…

CI/CD パイプラインが完走し、クラウド側で ソースの配置と起動に問題がなければ
GitLab からの ZIP デプロイによる CI/CD は正常に構成できたと言えます。

※artisan コマンドの実行について

Laravel では、デプロイ後に以下のような artisan コマンドを実行することがあります：

  • php artisan migrate（マイグレーション）
  • php artisan config:cache, route:cache, view:cache（キャッシュ系）
  • php artisan storage:link（ストレージ公開） など

CI/CD パイプライン内で自動実行する方法もありますが、
筆者は本番環境では SSH 経由で手動実行する運用としています。

特に php artisan migrate のようなコマンドは、実行失敗時の影響が大きいため、CI に組み込まず手動確認を挟む方が安全なケースもあります。

また、本番環境で storage/, bootstrap/cache/ ディレクトリの 書き込み権限（パーミッション） が不足していると artisan 実行が失敗することがあるため、
デプロイ先の環境に応じて chown や chmod による権限調整が必要になる場合もあります。

✅ 本記事のまとめと今後のポイント

本記事では、GitLab（独自ドメイン）と GitLab CI/CD を使い、Laravel アプリを
Azure App Service（コード方式）や AWS Elastic Beanstalk（ZIP方式）にデプロイするまでの
CI/CD パイプライン構築の基本フローを解説してきました。

ここまでのステップで、以下が確認できれば CI/CD の初期構築は完了です。

  • .gitlab-ci.yml によるビルド / デプロイの自動化
  • クラウド上への ZIP 配置の成功
  • GitLab 上の Pipeline 実行結果とログの確認

⚠️ よくある追加設定と今後のポイント

CI/CD の構築はアプリ公開の大きな第一歩ですが、アプリケーションの動作には追加の調整が必要になることもあります。

たとえば：

  • 環境変数（APP_KEY, DB 接続情報など）のクラウド側設定
  • Laravel の index.php が /public 以下にあることを前提としたルーティング構成
    • Azure App Service では /home/site/wwwroot/index.php が必要になるケースも
  • Apache / Nginx など Web サーバーごとの挙動差異
  • RDB や Redis 等の接続設定（Azure Database for MySQL、RDS など）
    • 筆者の構成では RDB に Amazon Aurora を使用しています。

今後の構築で関わる可能性がある AWS サービス（例）

使用AWSサービス

※こちらは、筆者自身が本記事の CI/CD を含むインフラ構築の中で実際に使用した AWS サービスの一覧です。
Elastic Beanstalk や S3 は CI/CD に直結するもので、その他のサービス（RDS や VPC など）はケースバイケースで使用が検討されるものです。
なお、筆者のインフラ構成は現在も拡張中のため、今後使用サービスが増減する可能性もあります。

こうした項目は、アプリケーションの構成や実行環境によって異なるため、今後のステップとして個別に検討・対応していく必要があります。

Discussion