Master GitLab CI for Symfony: Step‑by‑Step Pipeline Setup

In modern software development, Continuous Integration (CI) is essential for code quality and fast delivery. This guide walks you through configuring an efficient GitLab CI pipeline for a Symfony PHP project.

Step 1: Preparation

Before starting, ensure your project meets the following conditions:

Your Symfony project is hosted in a GitLab repository.

The root directory contains a .gitlab-ci.yml file, which defines all pipeline jobs.

You have a test suite (e.g., PHPUnit) ready, as testing is the core value of CI.

You are familiar with Docker (recommended) to guarantee environment consistency.

Step 2: Create the .gitlab-ci.yml File

In the root of your Symfony project, create a file named .gitlab-ci.yml.

Step 3: Configure Pipeline Stages

A typical Symfony CI pipeline includes the following stages ( stages): test: run unit and functional tests. lint: check code style and syntax (optional but recommended). security: perform security vulnerability scans (optional but strongly recommended). build: generate production assets (e.g., using Webpack Encore). deploy: deploy to test or production environments based on branch rules.

We will build this file step by step.

1. Choose a Base Image and Define Global Variables

First, specify a Docker image that includes PHP and Composer, and set some global cache variables.

# Use an official PHP image matching your project version
image: php:8.2-cli

# Define global cache key to speed up Composer dependency installation
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - vendor/
    - var/cache

# Scripts that run before all jobs
before_script:
  - apt-get update -yqq
  - apt-get install -yqq git unzip libzip-dev libicu-dev libpq-dev libonig-dev
  - docker-php-ext-install zip intl pdo_pgsql mbstring
  - pecl install xdebug && docker-php-ext-enable xdebug
  - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
  - composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader

2. Configure Specific Jobs

a. Code Static Analysis (Lint)

lint:php:
  stage: lint
  script:
    - composer validate # Validate composer.json
    - php bin/console lint:container # Check service container
    - php bin/console lint:twig templates/ # Check Twig templates
    - php bin/console lint:yaml config/ # Check YAML config files
  allow_failure: true # Continue pipeline even if this step fails

b. Run Tests (Test)

phpunit:
  stage: test
  script:
    - php bin/phpunit --coverage-text --colors=never
  artifacts:
    when: always
    reports:
      cobertura: coverage.xml
    paths:
      - var/log/test.log
    expire_in: 1 week
  coverage: '/^\s*Lines:\s*\d+.\d+%/'

Note: Ensure phpunit.xml.dist is configured to generate coverage.xml so GitLab can display a coverage chart.

c. Security Check (Security)

security:check:
  stage: security
  image: docker.io/composer:2.3
  before_script: []
  script:
    - composer require --dev symfony/security-checker
    - vendor/bin/security-checker security:check composer.lock
  allow_failure: true # Set to false if you want the pipeline to fail on vulnerabilities

d. Build Production Assets (Build)

If your project uses Webpack Encore for frontend assets:

build:assets:
  stage: build
  image: node:16
  cache:
    key: ${CI_COMMIT_REF_SLUG}-node
    paths:
      - node_modules/
      - public/build/
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - public/build/
  only:
    - main # Usually build assets only on the main branch or tags

Step 4: Advanced Optimizations and Practices

Use a custom Docker image that pre‑installs all required PHP extensions and dependencies to reduce pipeline runtime.

image: registry.your-company.com/your-team/php-with-extensions:8.2

Use the extends keyword to avoid repetition when multiple jobs share the same configuration.

.php-base: &php-base
  image: php:8.2-cli
  before_script:
    - ... # Common before_script

lint:php:
  <<: *php-base
  stage: lint
  script:
    - ...

phpunit:
  <<: *php-base
  stage: test
  script:
    - ...

Environment Variables and Database

Functional tests often need a database. Use the services keyword to start a temporary database container.

phpunit:
  stage: test
  services:
    - name: postgres:13-alpine
      alias: database
      variables:
        DATABASE_URL: "postgresql://postgres:password@database:5432/test_db"
  script:
    - php bin/console doctrine:schema:create -q
    - php bin/phpunit

Note: Store sensitive information such as database passwords and deployment keys securely in GitLab > Settings > CI/CD > Variables, not in plain text inside .gitlab-ci.yml.

Step 5: Trigger and Observe the Pipeline

After committing and pushing the .gitlab-ci.yml file to your GitLab repository, GitLab will automatically detect the file and start the pipeline.

Navigate to your GitLab project page.

Click on CI/CD > Pipelines in the sidebar.

You will see the pipeline triggered by the latest commit; click to view detailed logs and results for each job.

Conclusion

By following these steps, you have configured a feature‑rich GitLab CI pipeline for a Symfony project that automatically runs tests, checks code quality, performs security scans, and builds assets. CI/CD setup is iterative—start with a simple test stage and gradually add more stages and jobs to create a powerful, fully automated delivery pipeline that safeguards your Symfony development.