Building a Production-Ready GitLab CI/CD Pipeline for Laravel: From Testing to Deployment

7 min readUpdated on

A GitLab CI/CD pipeline for a Laravel app: tests and static analysis in parallel, one build job that produces a release tarball, and SSH deployment to a development and a production server.

Introduction

Below is the full .gitlab-ci.yml, split by stage, followed by the problems I hit most often. Deployment is plain scp and ssh, no orchestrator.

Pipeline Overview

Three stages:

  1. Test: the PHP and JavaScript jobs run in parallel
  2. Build: one job produces release.tar.gz
  3. Deploy: develop deploys to development automatically, main deploys to production after a manual click

Every job runs on a custom PHP 8.4 Docker image, and the cache is keyed on the lock files.

Prerequisites and Setup

Docker Image Configuration

The job image is a custom PHP 8.4 FPM image:

yaml
image: registry.gitlab.com/dommmin/gitlab-ci/php-8.4-fpm:latest

The image needs:

  • PHP 8.4 with extensions (mbstring, xml, bcmath, etc.)
  • Composer
  • Node.js and npm
  • Git
  • SQLite (for testing)

Environment Variables

Global variables:

yaml
variables:
  COMPOSER_NO_INTERACTION: 1
  COMPOSER_CACHE_DIR: .composer-cache
  NODE_VERSION: "22"
  FF_USE_FASTZIP: "true"
  TRANSFER_METER_FREQUENCY: "2s"
  COMPOSER_PROCESS_TIMEOUT: 2000
  COMPOSER_MEMORY_LIMIT: -1
  • COMPOSER_NO_INTERACTION: stops Composer from asking questions
  • FF_USE_FASTZIP: faster artifact compression
  • COMPOSER_MEMORY_LIMIT: removes Composer's memory limit

Stages and the shared dependency step used by the test jobs (*install_dependencies is a YAML alias, so the anchor has to be defined first):

yaml
stages:
  - test
  - build
  - deploy

# Shared step used as *install_dependencies in the test jobs
.install_dependencies: &install_dependencies
  - composer install --prefer-dist --no-progress
  - cp .env.example .env
  - php artisan key:generate

Caching Strategy

The cache key is derived from the lock files:

yaml
cache:
  key:
    files:
      - composer.lock
      - package-lock.json
  paths:
    - vendor/
    - node_modules/
    - .composer-cache/
  policy: pull-push
  when: on_success
  untracked: true

The cache changes only when composer.lock or package-lock.json changes. It holds vendor/, node_modules/ and .composer-cache/, is saved only when the job succeeds, and untracked: true adds every untracked file to it.

Pipeline Stages

Testing Stage

PHP Testing Job

yaml
test:php:
  stage: test
  services:
    - redis:latest
  variables:
    DB_CONNECTION: sqlite
    DB_DATABASE: ":memory:"
    SESSION_DRIVER: array
    CACHE_STORE: array
    QUEUE_CONNECTION: sync
  before_script:
    - *install_dependencies
    - echo "=== Building assets for PHP tests ==="
    - npm ci --no-audit --no-fund
    - npm run build
    - php artisan ziggy:generate
  script:
    - echo "=== Running PHP tests and analysis ==="
    - composer larastan || true
    - composer pint --test || true
    - ./vendor/bin/pest --log-junit=junit.xml --parallel
  artifacts:
    reports:
      junit: junit.xml
    paths:
      - public/build
    when: always
    expire_in: 1 week

In-memory SQLite keeps database tests fast, and Pest runs with --parallel and writes junit.xml for GitLab's test report. Larastan and Pint run too, but with || true, so they never fail the job. Only Pest can.

JavaScript Testing Job

yaml
test:js:
  stage: test
  before_script:
    - *install_dependencies
  script:
    - echo "=== Running JavaScript tests and analysis ==="
    - npm ci --no-audit --no-fund
    - npm run build
    - php artisan ziggy:generate
    - npm run format || true
    - npm run types || true
    - npm run lint || true
  artifacts:
    paths:
      - public/build
    when: always
    expire_in: 1 week

Despite the name there are no JavaScript tests here, only the asset build and three checks: npm run types, npm run lint and npm run format. All three end in || true, so like Larastan and Pint they report but never block.

Building Stage

The build job needs both test jobs and produces the release tarball:

yaml
build:
  stage: build
  environment:
    name: production
  needs:
    - test:php
    - test:js
  script:
    - echo "=== Building application ==="
    - composer install --optimize-autoloader --classmap-authoritative --no-dev --prefer-dist --no-interaction --no-progress
    - php artisan config:clear
    - php artisan route:clear
    - php artisan view:clear
    - php artisan ziggy:generate
    - echo "=== Building frontend assets ==="
    - npm ci --no-audit --no-fund
    - npm install -g dotenv-cli
    - dotenv -e $ENV_FILE -- npm run build:ssr
    - echo "=== Creating release package ==="
    - mkdir -p release
    - shopt -s extglob
    - cp -r !(release|.git|tests|node_modules|*.tar.gz|*.log|coverage.xml|junit.xml) release/
    - tar -czf release.tar.gz -C release .
    - rm -rf release
    - ls -lah release.tar.gz
    - echo "✅ Build completed successfully"
  artifacts:
    paths:
      - release.tar.gz
    expire_in: 1 day

Composer installs with --optimize-autoloader --classmap-authoritative --no-dev. The SSR build runs through npm run build:ssr with the env file injected by dotenv. The tarball leaves out .git, tests, node_modules and logs, and expires after a day.

Deployment Stage

Deployment Template

yaml
.deploy_template: &deploy_template
  stage: deploy
  image: alpine:3.19
  needs: [build]
  before_script:
    - apk add --no-cache openssh-client
    - mkdir -p ~/.ssh
    - echo "$SSH_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -p $SSH_PORT $SSH_HOST >> ~/.ssh/known_hosts
  script:
    - scp -P $SSH_PORT release.tar.gz $SSH_USER@$SSH_HOST:/home/$SSH_USER/laravel/ || exit 1
    - scp -P $SSH_PORT $ENV_FILE $SSH_USER@$SSH_HOST:/home/$SSH_USER/laravel/shared/.env || exit 1
    - scp -P $SSH_PORT deploy.sh $SSH_USER@$SSH_HOST:/home/$SSH_USER/laravel/ || exit 1
    - ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "cd laravel && chmod +x ./deploy.sh && ./deploy.sh" || exit 1

Environment-Specific Deployments

yaml
deploy_dev:
  <<: *deploy_template
  environment:
    name: development
  only:
    - develop

deploy_prod:
  <<: *deploy_template
  environment:
    name: production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
      allow_failure: false

develop deploys to development automatically. main deploys to production only after a manual click (when: manual), and allow_failure: false makes the pipeline wait on that job. The SSH key and host details come from CI variables.

Advanced Configuration

Parallel Testing

Tests run with pest --parallel:

yaml
script:
  - ./vendor/bin/pest --log-junit=junit.xml --parallel --processes=4

Artifact Management

The test jobs keep public/build and the JUnit report for a week. when: always keeps them even when tests fail:

yaml
artifacts:
  reports:
    junit: junit.xml
  paths:
    - public/build
  when: always
  expire_in: 1 week

Security Considerations

Keep SSH_KEY in a protected variable and the env file in a file-type variable. Restrict the deploy jobs to main and develop, and keep production manual.

Common Issues and Solutions

1. Memory Issues with Composer

Composer runs out of memory during installation. Remove its limit:

yaml
variables:
  COMPOSER_MEMORY_LIMIT: -1

2. Slow Asset Builds

  • Use npm ci instead of npm install
  • Cache node_modules/
  • Add --no-audit --no-fund

3. Test Database Issues

Database tests fail or are slow. Use in-memory SQLite:

yaml
variables:
  DB_CONNECTION: sqlite
  DB_DATABASE: ":memory:"

4. SSH Connection Failures

  • Check the key format (no Windows line endings, which is why the template runs tr -d '\r')
  • Add the host to known_hosts
  • Check firewall and port

5. Cache Invalidation

Builds use outdated cached dependencies. Key the cache on the lock files:

yaml
cache:
  key:
    files:
      - composer.lock
      - package-lock.json

Best Practices

1. Pipeline Optimization

Pin image tags. The job image and redis above both use :latest, so a green pipeline depends on whatever was pushed last.

2. Testing Strategy

Make the checks blocking. At the moment only Pest can fail a test job, because Larastan, Pint, types, lint and format all end in || true. Remove it once the codebase is clean.

3. Security

Rotate the SSH key from time to time and keep it in a protected variable.

4. Monitoring and Debugging

Keep junit.xml with when: always so failed runs stay inspectable, and set expire_in so artifacts don't pile up.

5. Environment Management

The deploy job copies $ENV_FILE to shared/.env on the server. Define it separately for development and production so each environment gets its own.

Conclusion

The pipeline tests, builds one tarball and deploys it over SSH, which is enough for a single-server Laravel app. First things to change: drop the || true from the quality checks and pin the image tags.

Related articles

Maintenance and growth

Do you need cleaner deployments or maintenance?

I help teams stabilize environments, improve release flow, and keep existing systems moving without unnecessary disruption.

Comments (0)
Sign in to leave a comment

You need to be signed in to add a comment.

Login

Need someone to take responsibility for the next step?

Let’s talk about your project and define a scope that actually makes sense for your goals.