This is the .gitlab-ci.yml I run for a Laravel app on GitLab: tests, three Docker images built with buildx, and a deploy over SSH.
1. Introduction
The pipeline tests the app, builds a Node, a PHP and an Nginx image, pushes them to the GitLab registry and deploys to one production server. Tests also run on merge requests; builds and deploy run only on main.
2. Pipeline Structure
Full Example: .gitlab-ci.yml
The complete file:
image: docker:latest
stages:
- test
- build
- deploy
variables:
DOCKER_BUILDKIT: 1
DOCKER_HOST: tcp://docker:2375/
DOCKER_TLS_CERTDIR: ""
IMAGE_NAMESPACE: dommmin/laravel-production
REGISTRY: registry.gitlab.com
services:
- docker:dind
before_script:
- docker info
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
test_php:
stage: test
image: dommin/php-8.4-fpm:latest
needs: [test_node]
before_script:
- git config --global --add safe.directory $(pwd)
- composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
script:
- cp .env.testing .env
- php artisan key:generate
- php artisan ziggy:generate
- composer larastan
- composer pint
- php artisan test --env=testing
variables:
DB_CONNECTION: sqlite
DB_DATABASE: ":memory:"
SESSION_DRIVER: array
artifacts:
paths:
- storage/logs/
expire_in: 1 week
only:
- main
- merge_requests
test_node:
stage: test
image: dommin/php-8.4-fpm:latest
before_script:
- git config --global --add safe.directory $(pwd)
- npm ci
- npm run build
script:
- npm run format
- npm run types
- npm run lint
artifacts:
paths:
- node_modules/
- public/build/
expire_in: 1 hour
only:
- main
- merge_requests
build_node:
stage: build
image: docker:24.0.5
needs: [test_node]
script:
- docker buildx create --use
- |
docker buildx build \
--platform linux/amd64 \
--file docker/node/Dockerfile \
--tag $REGISTRY/$IMAGE_NAMESPACE/node:latest \
--tag $REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
--push \
.
only:
- main
build_php:
stage: build
image: docker:24.0.5
needs: [test_php, build_node]
script:
- docker buildx create --use
- |
docker buildx build \
--platform linux/amd64 \
--file docker/php/Dockerfile \
--tag $REGISTRY/$IMAGE_NAMESPACE/php:latest \
--tag $REGISTRY/$IMAGE_NAMESPACE/php:$CI_COMMIT_SHA \
--push \
--build-context node=docker-image://$REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
.
only:
- main
build_nginx:
stage: build
image: docker:24.0.5
needs: [test_node, build_node]
script:
- docker buildx create --use
- |
docker buildx build \
--platform linux/amd64 \
--file docker/nginx/Dockerfile \
--tag $REGISTRY/$IMAGE_NAMESPACE/nginx:latest \
--tag $REGISTRY/$IMAGE_NAMESPACE/nginx:$CI_COMMIT_SHA \
--push \
--build-context node=docker-image://$REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
--build-arg HTPASSWD_USER="$HTPASSWD_USER" \
--build-arg HTPASSWD_PASS="$HTPASSWD_PASS" \
.
only:
- main
deploy_production:
stage: deploy
image: alpine:3.19
needs: [build_node, build_php, build_nginx]
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:
- cat "$ENV_FILE" > .env
- echo >> .env
- |
echo "REGISTRY=$REGISTRY" >> .env
echo "IMAGE_NAMESPACE=$IMAGE_NAMESPACE" >> .env
echo "NODE_IMAGE_NAME=$IMAGE_NAMESPACE/node" >> .env
echo "PHP_IMAGE_NAME=$IMAGE_NAMESPACE/php" >> .env
echo "NGINX_IMAGE_NAME=$IMAGE_NAMESPACE/nginx" >> .env
echo "TAG=$CI_COMMIT_SHA" >> .env
- scp -P $SSH_PORT docker-compose.production.yml $SSH_USER@$SSH_HOST:~/laravel/docker-compose.yml
- scp -P $SSH_PORT .env deploy.sh $SSH_USER@$SSH_HOST:~/laravel/
- echo "$CI_REGISTRY_PASSWORD" | ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY"
- ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "cd ~/laravel && chmod +x deploy.sh && ./deploy.sh"
only:
- main
3. Testing: PHP and Node
PHP Tests
The PHP job on its own:
test_php:
stage: test
image: dommin/php-8.4-fpm:latest
needs: [test_node]
before_script:
- composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
script:
- cp .env.testing .env
- php artisan key:generate
- php artisan ziggy:generate
- composer larastan
- composer pint
- php artisan test --env=testing
variables:
DB_CONNECTION: sqlite
DB_DATABASE: ":memory:"
SESSION_DRIVER: array
The job uses in-memory SQLite for speed and runs Larastan and Pint before the tests, so a static-analysis or style failure stops the pipeline. test_php waits for test_node (needs).
Node Tests
test_node:
stage: test
image: dommin/php-8.4-fpm:latest
before_script:
- npm ci
- npm run build
script:
- npm run format
- npm run types
- npm run lint
npm run format, npm run types and npm run lint check formatting, types and lint rules. The frontend is built first with npm run build, and node_modules/ and public/build/ are kept as artifacts for one hour.
4. Building Docker Images
Node, PHP and Nginx are built as separate images with docker buildx:
build_node:
stage: build
image: docker:24.0.5
needs: [test_node]
script:
- docker buildx create --use
- |
docker buildx build \
--platform linux/amd64 \
--file docker/node/Dockerfile \
--tag $REGISTRY/$IMAGE_NAMESPACE/node:latest \
--tag $REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
--push \
.
Images go to the GitLab registry, each tagged :latest and with the commit SHA. The production .env is deliberately not copied into the build context: anything baked into an image can be read by everyone who can pull it, so if Vite needs VITE_* values pass only those as build arguments. build_php and build_nginx work the same way, but take the Node image as an extra build context (--build-context node=docker-image://...), which is how the frontend build gets into them.
5. Automated Production Deployment
Deployment is SSH plus a bash script:
deploy_production:
stage: deploy
image: alpine:3.19
needs: [build_node, build_php, build_nginx]
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 docker-compose.production.yml $SSH_USER@$SSH_HOST:~/laravel/docker-compose.yml
- scp -P $SSH_PORT .env deploy.sh $SSH_USER@$SSH_HOST:~/laravel/
- echo "$CI_REGISTRY_PASSWORD" | ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY"
- ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "cd ~/laravel && chmod +x deploy.sh && ./deploy.sh"
The SSH key comes from a CI/CD variable. The job copies docker-compose.production.yml (as docker-compose.yml), .env and deploy.sh to ~/laravel/ and runs the script. In the full file the job first builds .env from $ENV_FILE and appends the registry and image names, with TAG=$CI_COMMIT_SHA. It then logs the server in to the registry over SSH, piping the job token through stdin so it is never written to .env or to disk (CI_REGISTRY_PASSWORD is only valid while the job runs).
6. Production Checklist & Best Practices
- ENV_FILE variable: pass the production environment as a file variable.
- SSH keys: store them in GitLab CI/CD Variables.
- Tests gate the build:
needsties the builds totest_phpandtest_node. - Image tags: every image is pushed as
:latestand as the commit SHA, and the deploy uses the SHA. To roll back, setTAGin the server.envto an earlier SHA and rundocker compose up -d. - Cache clearing: run
php artisan config:clearafter deployment.
7. Common Issues & Debugging
- Docker connection error: check that
docker:dindis running andDOCKER_HOSTis set. - SSH permission denied: the key needs
chmod 600and must reach the job intact (the full file strips\rwithtr -d). - Outdated images: buildx may be using its cache. Add
--no-cacheif needed. - Network issues: the production server must accept SSH connections from the runner.
8. Conclusion
That is the whole pipeline: test, build three images, deploy over SSH. It targets a single server, and the first thing I would change is pinning docker:latest, docker:dind and the PHP job image to fixed versions.