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:
- Test: the PHP and JavaScript jobs run in parallel
- Build: one job produces
release.tar.gz - Deploy:
developdeploys to development automatically,maindeploys 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:
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:
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 questionsFF_USE_FASTZIP: faster artifact compressionCOMPOSER_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):
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:
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
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
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:
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
.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
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:
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:
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:
variables:
COMPOSER_MEMORY_LIMIT: -1
2. Slow Asset Builds
- Use
npm ciinstead ofnpm install - Cache
node_modules/ - Add
--no-audit --no-fund
3. Test Database Issues
Database tests fail or are slow. Use in-memory SQLite:
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:
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.