.gitlab-ci.yml
├── stages (declared order)
├── variables (global)
├── default (defaults for all jobs)
├── include (other yaml files / templates)
└── <job_name>
    ├── stage
    ├── image (Docker image to run in)
    ├── services (sidecar containers)
    ├── before_script / script / after_script
    ├── rules (when to run)
    ├── needs (DAG dependencies)
    ├── artifacts (files to keep / pass between jobs)
    ├── cache (dependency cache)
    ├── environment (deployment target)
    └── tags (which runners can pick this up)

# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  PYTHON_VERSION: "3.12"

test:
  stage: test
  image: python:${PYTHON_VERSION}
  script:
    - pip install -r requirements.txt
    - pytest

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

deploy:
  stage: deploy
  script:
    - deploy.sh
  environment:
    name: production
    url: https://api.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

stages:
  - lint
  - test
  - build
  - deploy:staging
  - deploy:production

test:
  stage: test
  script: [...]

build:
  stage: build
  script: [...]
  # Implicit: runs after all jobs in `test` succeed

deploy:
  stage: deploy
  # explicit DAG; bypasses stage ordering
  needs: [build]
  script: [...]

build_backend:
  stage: build
  script: [...]

test_backend:
  stage: test
  needs: [build_backend]   # starts immediately after build_backend, even if build_frontend is still running
  script: [...]

build_frontend:
  stage: build
  script: [...]

test_frontend:
  stage: test
  needs: [build_frontend]
  script: [...]

deploy_prod:
  stage: deploy
  script: [...]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
    - if: $CI_COMMIT_TAG
      when: on_success
    - when: never        # default: don't run

test_python:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "**/*.py"
        - "requirements*.txt"

build:
  stage: build
  script:
    - python -m build
  artifacts:
    paths:
      - dist/*.whl
    expire_in: 1 week
    reports:
      junit: pytest-results.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

test:
  stage: test
  needs: [build]
  script:
    - pip install dist/*.whl
    - pytest

test:
  cache:
    key:
      files:
        - requirements.txt
        - poetry.lock
    paths:
      - .cache/pip
      - .venv/
  before_script:
    - pip install -r requirements.txt
  script:
    - pytest

deploy_staging:
  stage: deploy
  script: deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop_staging

stop_staging:
  stage: deploy
  script: teardown.sh staging
  environment:
    name: staging
    action: stop
  when: manual

test:
  image: python:3.14
  services:
    - name: postgres:16
      alias: db
      variables:
        POSTGRES_PASSWORD: test
    - redis:7

  variables:
    DATABASE_URL: postgres://postgres:test@db:5432/postgres
    REDIS_URL: redis://redis:6379

  script:
    - pip install -r requirements.txt
    - pytest

include:
  - local: .gitlab-ci-base.yml
  - project: org/templates
    file: python.yml
    ref: v1
  - template: Security/SAST.gitlab-ci.yml
  - remote: https://example.com/ci.yml

.test_template:
  image: python:3.14
  before_script:
    - pip install -r requirements.txt
  cache:
    paths: [.cache/pip]

test_unit:
  extends: .test_template
  stage: test
  script: pytest tests/unit

test_integration:
  extends: .test_template
  stage: test
  script: pytest tests/integration
  services:
    - postgres:16

deploy:
  tags:
    - production
    - aws
  script: deploy.sh

deploy_prod:
  stage: deploy
  script: deploy.sh prod
  when: manual
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - template: Security/Container-Scanning.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA