How to Deploy Laravel Application with CI/CD

How to Deploy Laravel Application with CI/CD

This guide shows a clear, practical path to deploy a Laravel app using CI/CD. You will learn how to build pipelines, test code, package artifacts, run containers, manage secrets, and handle releases and monitoring. Examples use common tools so you can adapt them to your platform.

Overview and objectives

Deploying Laravel with CI/CD means automating testing, building, and releasing code so deployments are faster and safer. The main objectives are:

• Run tests and checks on every change.
• Build reproducible artifacts or images.
• Deploy without surprises and with rollback options.
• Keep secrets safe and configuration consistent.
• Monitor app health and catch errors quickly.

By the end you should be able to create a CI pipeline that builds a Docker image, runs tests, and deploys to a cloud instance or container service.

Prerequisites and environment checklist

Before automating deployments, confirm you have:

• A Laravel app in a Git repository.
• Access to CI/CD service (GitHub Actions, GitLab CI, CircleCI, etc.).
• A container registry (Docker Hub, GitHub Container Registry, ECR).
• A server or container platform (VM, ECS, Kubernetes, DigitalOcean App Platform).
• Basic familiarity with Docker, Git, and composer.
• Backup strategy for your database and storage.
• Secrets storage (CI secrets, cloud secret manager, Vault).

On your local machine, install:

• PHP matching your app version.
• Composer.
• Node.js and npm/yarn for frontend assets.
• Docker and Docker Compose for local testing.

Repository layout and branching strategy

A clear repository layout reduces confusion:

• root/
  • app/ (Laravel app)
  • config/
  • database/
  • resources/
  • routes/
  • Dockerfile
  • docker-compose.yml
  • .github/workflows/ (CI pipelines)
  • tests/

Branching strategy that works:

• main (production-ready)
• develop (pre-production or staging)
• feature/* (work in progress)
• hotfix/* (urgent fixes)

Rules to follow:

• Merge to develop via pull requests after passing CI.
• Merge develop into main when ready to release.
• Tag releases using semantic versioning (v1.2.0).

This keeps master/main stable and lets CI gate merges.

Automated testing and code quality gates

Test and lint early in the pipeline. Typical checks:

• PHP unit tests: php artisan test or vendor/bin/phpunit
• Static analysis: PHPStan or Psalm
• Coding style: PHP-CS-Fixer or phpcs
• Security checks: composer audit, dependency scanners

A minimal test stage:

• Install PHP and extensions.
• composer install –prefer-dist –no-interaction
• Run static analysis then unit tests.
• Fail fast on errors.

Example commands:

• composer install –no-progress –no-suggest –prefer-dist
• vendor/bin/phpstan analyse
• php artisan test –testsuite=Feature

Gate rules:

• Do not allow merges if tests or analysis fail.
• Run tests on branches and for pull requests.
• Run full test suite on merges to main.

Continuous integration pipeline setup

CI pipelines should be simple, fast, and reproducible. Typical pipeline stages:

1. Setup environment (PHP, composer, node)
2. Install dependencies
3. Run linters and static analysis
4. Run unit and integration tests
5. Build frontend assets
6. Build Docker image or package artifact
7. Push image/artifact to registry

Simple GitHub Actions workflow (shortened):

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
      - name: Install Composer deps
        run: composer install --no-progress --no-suggest --prefer-dist
      - name: Run static analysis
        run: vendor/bin/phpstan analyse
      - name: Run tests
        run: php artisan test --verbose
      - name: Build assets
        run: |
          npm ci
          npm run build
      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          push: true
          tags: user/app:${{ github.sha }}

Adjust versions and actions to your CI provider.

Build artifacts and packaging

Decide whether your deployment uses container images or artifacts (ZIPs/tarballs). Images are preferred for consistent runtime.

Artifact tips:

• Use composer install –no-dev for production builds.
• Run php artisan config:cache and route:cache during image build.
• Precompile frontend assets (Vite or Mix) and include them in the image.
• Tag images with commit SHA and semantic tag.

Example build commands for production:

• composer install –no-dev –optimize-autoloader
• npm ci && npm run build
• php artisan config:clear && php artisan config:cache
• php artisan route:cache

Keep the build environment isolated so builds are reproducible.

Containerization with Docker and Docker Compose

Use a multi-stage Dockerfile to keep images small and secure.

Example Dockerfile (multi-stage):

FROM php:8.1-fpm AS base
WORKDIR /app
RUN apt-get update && apt-get install -y git unzip libonig-dev libzip-dev 
    && docker-php-ext-install pdo_mysql mbstring zip bcmath
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
COPY . /app
RUN composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
RUN npm ci && npm run build
RUN php artisan config:cache && php artisan route:cache

FROM php:8.1-fpm AS final
WORKDIR /app
COPY --from=base /app /app
CMD ["php-fpm"]

Local development with Docker Compose:

• Services: app (php-fpm), web (nginx), db (mysql/postgres), redis, queue worker.
• Mount code as volume in dev, but not in production image.
• Use docker-compose.override.yml for developer overrides.

Keep development and production compose files separate to avoid leaking dev tools into production.

Managing environment variables and secrets

Never commit .env to the repository. Use these options for secrets:

• CI/CD secrets (GitHub Actions secrets, GitLab CI variables)
• Cloud secret managers (AWS Secrets Manager, Parameter Store, Azure Key Vault)
• HashiCorp Vault for central secret storage
• Docker secrets for swarm or Kubernetes Secrets for k8s

Best practices:

• Store only non-sensitive defaults in repo (example.env).
• Inject secrets at runtime from CI environment or orchestration platform.
• Avoid baking secrets into images.
• Use php artisan config:cache carefully — only after environment variables are set.

Example: in GitHub Actions deploy job, pass secrets as environment variables when running remote deploy scripts.

Deployment strategies and release management

Choose a deployment strategy that fits risk tolerance:

• Rolling: update instances a few at a time. Good for minimal downtime in clusters.
• Blue/Green: switch traffic between two identical environments. Good for easy rollback.
• Canary: release to a subset of users first. Good for gradual exposure.
• Immutable releases: deploy new instances with new image, then replace old ones.

Release management tips:

• Tag builds with semantic versions and commit SHA.
• Keep a changelog and link commits to tickets.
• For database changes, prefer backward-compatible migrations:
  • Add columns first, deploy, then fill data, then remove old columns later.
• Avoid running destructive rollback migrations on production unless you have a backup.

Automated deploy step (example):

• Pull image by tag
• Run health checks
• Run migrations with –force if safe
• Restart queue workers
• Switch traffic if using load balancer

Infrastructure provisioning and IaC

Treat infrastructure as code so environments are repeatable:

• Use Terraform or CloudFormation to provision servers, load balancers, and databases.
• Keep IaC in its own repository or in a separate folder with clear separation from app code.
• Apply changes via CI/CD with approval gates for production.

Basic Terraform workflow:

• terraform plan (in CI) to show changes
• terraform apply (with manual approval for prod)

Key resources to manage:

• Networking (VPC, subnets, security groups)
• Compute (instances, container services)
• Storage (databases, S3 buckets)
• DNS and load balancers
• IAM roles and policies

Version your IaC and review changes like code.

Monitoring, rollback, and maintenance

Monitoring:

• Collect application logs and centralize them (ELK, CloudWatch, LogDNA).
• Use error tracking (Sentry, Bugsnag).
• Use metrics (Prometheus, Datadog) for latency, request rates, queue lengths.
• Set alerts on error spikes, CPU, memory, and failed migrations.

Rollback:

• Keep previous image or artifact available for fast rollback.
• Revert the deployment to the last known-good tag and run health checks.
• Do not run destructive migration rollbacks without a tested plan.
• For data-corrupting issues, restore from backup after analysis.

Maintenance:

• Schedule maintenance windows for risky tasks.
• Backup databases and file storage regularly and test restores.
• Rotate secrets and credentials on a schedule.
• Keep dependencies and PHP up to date and apply security patches.

Health check example:

• Expose a lightweight /health endpoint that checks DB connectivity and cache.
• Make the endpoint return minimal info and secure it as needed.

Final advice: automate health checks and rollbacks in your pipeline where possible.

Monitoring, rollback, and maintenance

(Repeated heading in TOC; treating as continuation for operational detail)

Operational preparedness:

• Create runbooks for common incidents (failed deploy, DB migration issue).
• Automate routine maintenance: backups, cache clearing, log rotation.
• Test rollback and restore procedures regularly in a staging environment.

Migrations and downtime:

• Run migrations in a safe order and test on staging.
• Consider splitting large migrations into smaller steps.
• Use maintenance mode when necessary: php artisan down/up but use it only when unavoidable.

Post-deploy checks:

• Smoke test endpoints automatically after deployment.
• Check error rates and response times for a given post-deploy window.
• Notify the team via Slack or email on successful or failed deploys.

Conclusion

A reliable CI/CD deployment for Laravel combines automated testing, predictable builds, safe secret handling, and observable production. Start small: add CI tests, build artifacts, and push images. Then add deployment automation, IaC, and monitoring. Keep deployments repeatable, reversible, and well-documented so your team can move fast with confidence.