Multi-Stage GitLab CI Pipeline Architecture

Multi-Stage Pipeline Architecture

GitLab CI stages define the order in which groups of jobs execute. A well-designed stage architecture balances speed (parallelism) with correctness (dependency ordering).

Linear Pipeline

stages:
  - build
  - test
  - staging
  - production

build:
  stage: build
  script:
    - make build
  artifacts:
    paths:
      - dist/

unit_tests:
  stage: test
  script:
    - make test-unit

integration_tests:
  stage: test
  script:
    - make test-integration

deploy_staging:
  stage: staging
  script:
    - make deploy-staging
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

deploy_production:
  stage: production
  script:
    - make deploy-production
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

DAG Pipeline with needs

stages:
  - build
  - test
  - deploy

build_frontend:
  stage: build
  script: make build-frontend
  artifacts:
    paths: [dist/frontend/]

build_backend:
  stage: build
  script: make build-backend
  artifacts:
    paths: [dist/backend/]

test_frontend:
  stage: test
  needs: [build_frontend]
  script: make test-frontend

test_backend:
  stage: test
  needs: [build_backend]
  script: make test-backend

deploy:
  stage: deploy
  needs: [test_frontend, test_backend]
  script: make deploy

Fan-Out / Fan-In

The DAG example above demonstrates fan-out (build splits into frontend and backend) and fan-in (deploy waits for both test jobs). This pattern is faster than linear stages because test_frontend does not wait for build_backend.

Stage Design Guidelines

1. Keep stages coarse-grained: 3-5 stages is typical. Too many stages add overhead.
2. Use needs for fine-grained dependencies: DAG pipelines within stages provide the best of both worlds.
3. Separate deploy stages by environment: staging and production should be distinct stages with manual approval for production.