GitLab CI/CD Cheatsheet: Pipelines, Jobs and Rules Reference

# 1. Minimal .gitlab-ci.yml at repo root — that's all you need to enable CI
cat > .gitlab-ci.yml <<'YAML'
default:
    image: python:3.12

stages: [build, test, deploy]

test:
    stage: test
    script:
        - pip install -r requirements.txt
        - pytest -q
YAML

git add .gitlab-ci.yml && git commit -m "ci: enable pipelines" && git push

# 2. Validate locally without pushing
glab ci lint                                # GitLab CLI
# or with the official Docker image
docker run --rm -v "$PWD:/work" -w /work registry.gitlab.com/gitlab-org/cli:latest \
    glab ci lint .gitlab-ci.yml

# 3. Run pipelines on your laptop (preview)
gitlab-runner exec docker test              # runs the "test" job locally in Docker

# 4. Register a self-hosted runner
sudo gitlab-runner register \
    --url https://gitlab.com/ \
    --registration-token  \
    --executor docker \
    --description "linux-docker" \
    --tag-list "docker,linux" \
    --docker-image "alpine:latest"

# 5. Tail runner logs
sudo gitlab-runner --debug run

# Full pipeline: build → test (parallel matrix) → deploy (manual on main).
default:
    image: python:3.12
    interruptible: true                  # cancel obsolete runs on new pushes

stages: [build, test, deploy]

variables:
    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
    key: "$CI_COMMIT_REF_SLUG"            # branch-scoped cache
    paths: [.cache/pip/, .venv/]
    policy: pull-push

.python_base: &python_base
    before_script:
        - python -m venv .venv && . .venv/bin/activate
        - pip install -r requirements.txt

build:
    <<: *python_base
    stage: build
    script: [python -m build]
    artifacts: { paths: [dist/], expire_in: 1 week }

test:
    <<: *python_base
    stage: test
    parallel:
        matrix:
            - PYTHON: ["3.11", "3.12"]
    image: "python:$PYTHON"
    script: [pytest -q --junitxml=junit.xml]
    artifacts:
        when: always
        reports: { junit: junit.xml }

deploy_prod:
    stage: deploy
    needs: [build]
    environment: { name: production, url: https://app.example.com }
    rules:
        - if: '$CI_COMMIT_BRANCH == "main"'
          when: manual
    script: [./scripts/deploy.sh]

# rules: are evaluated top to bottom — first match wins.
# Combine if/changes/exists to express precise triggers.

# 1. Only on merge requests against main
mr_lint:
    script: [./scripts/lint.sh]
    rules:
        - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main"'

# 2. Skip if only docs changed
build:
    script: [make]
    rules:
        - changes: { paths: ["docs/**/*", "*.md"], compare_to: "main" }
          when: never
        - when: on_success

# 3. Manual job; allow_failure so it doesn't block
deploy_canary:
    script: [./deploy_canary.sh]
    rules:
        - if: '$CI_COMMIT_BRANCH == "main"'
          when: manual
          allow_failure: true

# 4. Pipeline-level — skip the whole run on draft MRs
workflow:
    rules:
        - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TITLE =~ /^Draft:/'
          when: never
        - when: always

# 5. Scheduled-only job
nightly_db_dump:
    script: [./scripts/dump.sh]
    rules:
        - if: '$CI_PIPELINE_SOURCE == "schedule"'

# Variables live in three places:
#   1. .gitlab-ci.yml (visible to anyone reading the repo)
#   2. Project / Group / Instance settings → CI/CD → Variables (masked + protected)
#   3. Vault / OIDC at runtime (no static secret in GitLab)

variables:
    NODE_ENV: production
    REGION:   us-east-1
    BUILD_NUMBER:
        value: "1"
        description: "Override via 'Run pipeline'"   # surfaces a form field in the UI

deploy:
    image: hashicorp/terraform:1.7
    # Each `id_tokens` block requests a JWT — exchange it for short-lived creds.
    id_tokens:
        AWS_JWT: { aud: https://gitlab.com }
    before_script:
        # Trade the JWT for AWS creds via OIDC
        - aws sts assume-role-with-web-identity
            --role-arn "$AWS_ROLE_ARN"
            --role-session-name "gitlab-$CI_PIPELINE_ID"
            --web-identity-token "$AWS_JWT" > creds.json
        - export AWS_ACCESS_KEY_ID=$(jq -r .Credentials.AccessKeyId creds.json)
        - export AWS_SECRET_ACCESS_KEY=$(jq -r .Credentials.SecretAccessKey creds.json)
        - export AWS_SESSION_TOKEN=$(jq -r .Credentials.SessionToken creds.json)
    script:
        - echo "Deploying $CI_COMMIT_SHORT_SHA to $CI_ENVIRONMENT_NAME"
        - terraform apply -auto-approve
    environment: { name: production }
    rules:
        - if: '$CI_COMMIT_BRANCH == "main"'

# include + extends: keep .gitlab-ci.yml short, share templates across repos.

include:
    # 1. From this repo
    - local: .ci/lint.yml

    # 2. From another GitLab project at a specific ref
    - project: "platform/templates"
      file:    "/ci/python.yml"
      ref:     "v3"

    # 3. Reusable CI/CD component (GitLab catalog)
    - component: gitlab.com/components/sast@1.0.0
      inputs:
          stage: test

    # 4. GitLab-provided template (full list under "Pipeline Editor → Browse templates")
    - template: "Security/Container-Scanning.gitlab-ci.yml"

# Hidden jobs (leading dot) act as reusable bases.
.python_base:
    image: python:3.12
    before_script:
        - pip install -r requirements.txt

# Extend one or several bases — keys are deep-merged.
test:
    extends: .python_base
    script: [pytest -q]

lint:
    extends: [.python_base, .needs_no_cache]
    script: [ruff check .]

# !reference grabs a specific key from another job — clearer than YAML anchors.
type_check:
    extends: .python_base
    script:
        - !reference [.python_base, before_script]
        - mypy src

# End-to-end: lint → test → build → deploy.
# Review apps on every MR, manual prod deploy from main.
default:
    image: node:20-alpine
    interruptible: true

stages: [lint, test, build, deploy]

variables:
    NPM_CONFIG_CACHE: "$CI_PROJECT_DIR/.npm"

cache:
    key: "$CI_COMMIT_REF_SLUG"
    paths: [.npm/, node_modules/]
    policy: pull-push

.node_setup: &node_setup
    before_script: [npm ci --prefer-offline]

lint:
    <<: *node_setup
    stage: lint
    script: [npm run lint]

unit:
    <<: *node_setup
    stage: test
    script: [npm test -- --ci]
    artifacts: { when: always, reports: { junit: junit.xml } }

build:
    <<: *node_setup
    stage: build
    script: [npm run build]
    artifacts: { paths: [dist/], expire_in: 1 week }
    needs: [lint, unit]

review:
    stage: deploy
    needs: [build]
    environment:
        name: review/$CI_COMMIT_REF_SLUG
        url:  https://$CI_COMMIT_REF_SLUG.preview.example.com
        on_stop: stop_review
        auto_stop_in: 1 week
    rules:
        - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    script: [./scripts/deploy_review.sh]

stop_review:
    stage: deploy
    rules: [{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"', when: manual, allow_failure: true }]
    environment: { name: review/$CI_COMMIT_REF_SLUG, action: stop }
    script: [./scripts/stop_review.sh]

deploy_prod:
    stage: deploy
    needs: [build]
    environment: { name: production, url: https://app.example.com }
    resource_group: production            # serialize prod deploys
    rules: [{ if: '$CI_COMMIT_BRANCH == "main"', when: manual }]
    script: [./scripts/deploy.sh]