Skip to main content

GitLab CI Practices and Standards

Introduction​

This document defines the GitLab CI/CD practices and standards for the Publica.la platform. Our CI/CD pipeline is a critical component of our development workflow, ensuring code quality, automated testing, and reliable deployments across all our services. By following these standards, we maintain consistency across projects, improve developer experience, and enable efficient automation and monitoring.

The standardized approach outlined here applies to all repositories in the Publica.la platform ecosystem, from our core monolithic application (Farfalla) to specialized services like content processing (Castoro) and reader applications (Volpe, Fenice).

Job Naming Convention​

GitLab CI job naming uses a hierarchical, colon-separated format that indicates each job's purpose and scope.

Standard Format​

[modifier:]action[:type][:tool][:environment][:target]

Each component serves a specific purpose:

  • [modifier] (optional): Special conditions like force, manual, scheduled
  • action: The primary verb describing what the job does
  • [:type] (optional): Specific type of action being performed
  • [:tool] (optional): Specific tool being used
  • [:environment] (optional): Target environment
  • [:target] (optional): Specific deployment target or service

Separator Rules​

We use consistent separators to maintain clarity and enable programmatic parsing:

  • Use : as the primary separator between all components
  • Use - only within a component for multi-word terms (e.g., install-deps, docker-compose)
  • Components are ordered from general to specific

Action Verbs​

Each job begins with a standardized action verb that clearly indicates its primary function:

  • install: Installing dependencies only (no building or compilation)
  • build: Building or compiling code (may include dependency installation if required)
  • test: Running any type of tests
  • analyze: Performing static code analysis
  • scan: Executing security or vulnerability scanning
  • lint: Checking code style and formatting
  • deploy: Deploying to environments
  • notify: Sending notifications or alerts
  • validate: Performing validation checks
  • generate: Creating reports, artifacts, or documentation

Standard Job Examples​

Build Stage Jobs​

Build stage jobs for codebase preparation:

  • install:php: Install PHP dependencies via Composer
  • install:js: Install JavaScript dependencies via npm/yarn
  • build:js: Build JavaScript project (includes dependency installation)
  • build:assets: Compile and optimize frontend assets
  • build:docs: Generate documentation
  • build:db: Prepare database schemas or seed data

Test Stage Jobs​

Testing jobs for code quality and functionality:

  • test:all: Run comprehensive test suite (unit + integration + e2e)
  • test:unit:php: Execute PHP unit tests
  • test:unit:js: Execute JavaScript unit tests
  • test:integration:api: Run API integration tests
  • test:e2e:storefront: End-to-end tests for storefront functionality
  • test:external: External validation tests
  • lint:php: PHP code style checking
  • lint:js: JavaScript code style checking
  • analyze:static:phpstan: Static analysis using PHPStan
  • analyze:duplication:phpcpd: Code duplication detection

Deploy Stage Jobs​

Deployment jobs for releasing code to environments:

  • deploy:staging: Deploy to staging environment
  • deploy:production: Deploy to production environment
  • deploy:staging:farfalla: Deploy Farfalla service to staging
  • deploy:production:fenice: Deploy Fenice to production
  • force:deploy:staging:volpe: Force deployment of Volpe to staging
  • test:deploy:staging: Verify deployment success on staging

Security Scanning Jobs​

Security jobs for vulnerability identification:

  • scan:sast:semgrep: Static Application Security Testing with Semgrep
  • scan:deps:composer: Scan Composer dependencies for vulnerabilities
  • scan:deps:yarn: Scan Node.js dependencies for vulnerabilities
  • scan:secrets: Scan for exposed secrets or credentials

Pipeline Stages​

Projects use only the stages they require from the standard set:

stages:
  - build
  - test
  - deploy
  - post-deploy

Stage Definitions​

build: Dependency installation and asset compilation

test: Unit tests, integration tests, code style checks, static analysis, and security scanning

deploy: Environment deployments and deployment verification

post-deploy: External validation tests and deployment notifications

Implementation Guidelines​

When Creating New Jobs​

When adding new CI jobs to any project, follow these guidelines:

  1. Choose the appropriate action verb from our standardized list
  2. Add specificity as needed using the hierarchical format
  3. Place the job in the correct stage based on its function
  4. Maintain consistency with existing jobs in the project

Environment Naming​

Use consistent environment names across all projects:

  • staging: Staging environment
  • production: Production environment
  • dev or development: Development environment
  • test: Test environment (different from staging)

Special Modifiers​

Use modifiers sparingly and only when they add clear value:

  • force:: Bypasses certain checks or validations
  • manual:: Requires manual trigger (though GitLab's when: manual is preferred)
  • scheduled:: Runs on a schedule
  • test:: Indicates a test deployment or dry run

Matrix Builds and Parallel Jobs​

For jobs that run across multiple versions or in parallel:

  • Version-specific: test:unit:php:8.2, test:unit:node:20
  • Parallel chunks: test:unit:php:parallel-1, test:unit:php:parallel-2

Best Practices​

Job Dependencies​

When defining job dependencies, use the standardized job names consistently:

test:all:
  stage: test
  needs: ["install:php", "build:js"]

Resource Groups​

Use resource groups to prevent concurrent deployments:

deploy:production:
  stage: deploy
  resource_group: production

Caching Strategy​

Implement caching to speed up pipelines:

install:php:
  cache:
    key: "$CI_COMMIT_REF_SLUG-composer"
    paths:
      - vendor/

Artifact Management​

Define artifacts clearly for jobs that produce them:

build:js:
  artifacts:
    paths:
      - public/build/
    expire_in: 1 week

Common Patterns Across Projects​

Laravel Projects​

Laravel-based services (Farfalla, Medusa, Coniglio) typically include:

  • install:php: Composer dependency installation
  • build:js: Frontend asset compilation
  • test:all: Comprehensive test suite (PHPUnit/Pest)
  • analyze:static:phpstan: Static analysis
  • deploy:staging and deploy:production: Environment deployments

JavaScript Projects​

JavaScript services (Volpe, Vito, Micelio) commonly use:

  • build:js: Build and bundle JavaScript
  • test:unit:js: JavaScript unit tests
  • lint:js: ESLint or similar code style checking
  • deploy:staging and deploy:production: Deployment jobs

Testing Projects​

Testing-focused repositories (Criceto) include specialized jobs:

  • test:integration:api: API testing
  • test:e2e:storefront: End-to-end UI tests
  • generate:reports:kpi: Test report generation

Migration from Legacy Names​

When updating existing CI configurations, reference these common migrations:

  • composer → install:php
  • yarn or npm → build:js or install:js
  • phpunit → test:all or test:unit:php
  • staging → deploy:staging
  • production → deploy:production
  • external_test stage → post-deploy stage

Monitoring and Compliance​

To ensure continued adherence to these standards:

  1. Code Review: Reviewers should verify CI configuration changes follow these standards
  2. Documentation: Keep this document updated as standards evolve
  3. Automation: Consider implementing CI linting tools to validate job naming
  4. Training: Ensure all developers understand and follow these conventions
X

Graph View