CI/CD Cheatsheet

Kurzreferenz für Ansible-Automatisierung, Playbooks, Module und Best Practices

Ein praktischer Quick-Reference-Guide für die zwei populärsten CI/CD-Plattformen. Er behandelt Workflow-Syntax, Trigger, Secrets, Artifacts, Caching, Matrix-Builds sowie praxisnahe Deployment-Patterns für GitHub Actions und GitLab CI.

GitHub Actions

GitHub Actions ist die integrierte CI/CD-Plattform für GitHub-Repositories. Workflows werden in YAML-Dateien unter .github/workflows/ definiert und durch Repository-Events, Zeitpläne oder manuellen Dispatch ausgelöst.

Workflow-Struktur

Jeder Workflow befindet sich in .github/workflows/<name>.yml und benötigt einen name, einen on (Trigger) sowie mindestens einen job mit steps.

name: CI Pipeline

# Triggers — what starts this workflow
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 6 * * 1" # Every Monday at 06:00 UTC
  workflow_dispatch: # Manual trigger from GitHub UI

# Global environment variables
env:
  NODE_VERSION: "20"
  REGISTRY: ghcr.io

jobs:
  build-and-test:
    name: Build & Test
    runs-on: ubuntu-latest
    timeout-minutes: 15

    # Job-level environment variables
    env:
      APP_DIR: ./apps/web

    # Job-level permissions
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm run test -- --coverage

      - name: Build application
        run: npm run build

Trigger

Steuern Sie den Zeitpunkt der Workflow-Ausführung mit feingranularen Event-Filtern.

on:
  # Push auf spezifische Branches oder Tags
  push:
    branches:
      - main
      - "release/**"
    tags:
      - "v*"

  # Pull Request auf spezifische Branches
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]

  # Ausführung nach Zeitplan (Cron-Syntax, UTC)
  schedule:
    - cron: "0 0 * * *" # Täglich um Mitternacht
    - cron: "0 6 * * 1" # Jeden Montag um 06:00

  # Manueller Trigger mit Inputs
  workflow_dispatch:
    inputs:
      environment:
        description: "Deployment environment"
        required: true
        default: staging
        type: choice
        options:
          - staging
          - production
      debug_mode:
        description: "Enable debug logging"
        required: false
        type: boolean
        default: false

  # Trigger bei Abschluss eines Workflows
  workflow_run:
    workflows: ["CI Pipeline"]
    types: [completed]
    branches: [main]

  # Trigger bei Issues oder anderen Events
  issues:
    types: [opened, labeled]
  release:

types: [published]

### Using Actions from the Marketplace

Reference community or first-party actions with `uses`. Pin by tag or SHA (SHA is recommended for security).

```yaml
steps:
  # First-party GitHub Actions
  - uses: actions/checkout@v4 # Repo klonen
  - uses: actions/setup-node@v4 # Node.js installieren
  - uses: actions/setup-python@v5 # Python installieren
  - uses: actions/setup-java@v4 # JDK installieren
  - uses: actions/setup-go@v5 # Go installieren
  - uses: actions/cache@v4 # Abhängigkeiten cachen
  - uses: actions/upload-artifact@v4 # Build-Artefakte hochladen
  - uses: actions/download-artifact@v4 # Artefakte herunterladen
  - uses: actions/labeler@v5 # PRs automatisch labeln
  - uses: actions/create-release@v1 # GitHub Release erstellen
  - uses: actions/configure-pages@v5 # GitHub Pages einrichten
  - uses: actions/deploy-pages@v4 # Auf Pages deployen

  # Third-party (aus Sicherheitsgründen per SHA fixiert)
  - uses: docker/login-action@v3 # In Container-Registry einloggen
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

  - uses: docker/build-push-action@v5 # Docker-Image bauen und pushen
    with:
      context: .
      push: true
      tags: ${{ env.REGISTRY }}/${{ github.repository }}:${{ github.sha }}

  - uses: docker/setup-buildx-action@v3 # BuildKit einrichten

  # Referenz auf eine lokale Action im selben Repo
  - uses: ./.github/actions/custom-action

Environment Variables and Secrets

GitHub provides context expressions, repository secrets, and environment variables at multiple scopes.

on: push

env:
  # Global für alle Jobs
  APP_NAME: myapp
  NODE_ENV: production

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Erforderliche Umgebung mit Schutzregeln

    env:
      # Variable auf Job-Ebene
      DEPLOY_PATH: /var/www/${{ env.APP_NAME }}

    steps:
      # Integrierte Umgebungsvariablen (immer verfügbar)
      - name: Show built-in vars
        run: |
          echo "Home: $HOME"
          echo "Runner OS: $RUNNER_OS"
          echo "Runner Arch: $RUNNER_ARCH"
          echo "Workspace: $GITHUB_WORKSPACE"
          echo "Event: $GITHUB_EVENT_NAME"
          echo "SHA: $GITHUB_SHA"
          echo "Ref: $GITHUB_REF"

      # Repository-Secrets verwenden (festgelegt in Settings > Secrets)
      - name: Deploy with credentials
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
          API_KEY: ${{ secrets.API_KEY }}
          # GITHUB_TOKEN ist automatisch verfügbar
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          echo "Deploying to $DEPLOY_PATH"
          # Variablen sicher verwenden — Secrets niemals per echo ausgeben
          deploy.sh --password "$DB_PASSWORD"

      # Kontext-Ausdrücke verwenden
      - name: Use context data
        run: |
          echo "Actor: ${{ github.actor }}"
          echo "Repo: ${{ github.repository }}"
          echo "Branch: ${{ github.ref_name }}"
          echo "Event: ${{ github.event_name }}"

      # Umgebungsspezifische Secrets verwenden
      - name: Use environment secret
        env:
          PROD_API_KEY: ${{ secrets.PROD_API_KEY }}
        run: echo "Secret length: ${#PROD_API_KEY}"

      # Mehrzeilige Umgebungsvariable
      - name: Set multi-line variable
        env:
          SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key

Artifacts and Caching

Share data between jobs and speed up workflows by caching dependencies.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
- uses: actions/checkout@v4

      # npm-Abhängigkeiten cachen
      - uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - run: npm ci
      - run: npm run build

      # Build-Output als Artifact hochladen
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
          retention-days: 14
          if-no-files-found: error

      # Testergebnisse hochladen
      - uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: coverage/
          retention-days: 7

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      # Artifact aus dem Build-Job herunterladen
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/

      - name: Deploy
        run: deploy.sh dist/

      # Deployment-Logs als Artifact hochladen
      - uses: actions/upload-artifact@v4
        if: always() # Auch hochladen, wenn vorherige Schritte fehlschlagen
        with:
          name: deploy-logs
          path: logs/

Matrix Builds

Run jobs across multiple versions, platforms, or configurations in parallel.

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      # Laufende Jobs nicht abbrechen, wenn einer fehlschlägt
      fail-fast: false

      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [18, 20, 22]
        # Spezifische Kombinationen ausschließen
        exclude:
          - os: windows-latest
            node-version: 18
        # Zusätzliche Kombinationen hinzufügen
        include:
          - os: ubuntu-latest
            node-version: 22
            experimental: true
            label: "Node 22 (experimental)"

    name: Test on Node ${{ matrix.node-version }} (${{ matrix.os }})
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test
      - run: npm run test:integration
        if: matrix.experimental

Reusable Workflows

Call workflows from other workflows to share CI logic across repositories.

# .github/workflows/reusable-build.yml (der wiederverwendbare Workflow)
name: Reusable Build

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "20"
      build-command:
        required: false
        type: string
        default: "npm run build"
    secrets:
      registry-token:
        required: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
      - run: ${{ inputs.build-command }}

# .github/workflows/ci.yml (der Aufrufer)
name: CI

on:
  push:
    branches: [main]

jobs:
  call-build:
    uses: ./.github/workflows/reusable-build.yml
    with:
      node-version: "22"
      build-command: "npm run build:prod"
    secrets:
      registry-token: ${{ secrets.GITHUB_TOKEN }}

  # Aufruf aus einem anderen Repository
  call-external:
    uses: myorg/shared-actions/.github/workflows/deploy.yml@v2
    with:
      environment: staging
    secrets:
      deploy-key: ${{ secrets.STAGING_DEPLOY_KEY }}

Self-Hosted Runners

Run workflows on your own infrastructure instead of GitHub-hosted runners.

jobs:
  build-on-prem:
    runs-on: [self-hosted, linux, x64]
    # Oder ein benutzerdefiniertes Label verwenden
    # runs-on: self-hosted-gpu

    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "Running on self-hosted runner"
          echo "Runner name: $RUNNER_NAME"
          echo "OS: $(uname -a)"

  # Runner-Gruppen verwenden (Enterprise/Team)
  deploy-production:
    runs-on:
      - self-hosted
      - linux
      - production # Benutzerdefiniertes Label für Prod-Runner
    environment: production
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh

Complete Real-World Example: Node.js CI/CD

name: Node.js CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read
  packages: write
  id-token: write

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck

  test:
    name: Test
    needs: lint
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - uses: actions/upload-artifact@v4
        if: matrix.node-version == 20
        with:
          name: coverage-report
          path: coverage/

  build:
    name: Build & Push Image
needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    outputs:
      image-tag: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=
            type=ref,event=branch
            type=semver,pattern={{version}}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy-staging:
    name: Deploy to Staging
    needs: build
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to staging
        run: |
          echo "Deploying image tag: ${{ needs.build.outputs.image-tag }}"
          # kubectl set image deployment/web app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.build.outputs.image-tag }}
          # kubectl rollout status deployment/web

  deploy-production:
    name: Deploy to Production
    needs: [build, deploy-staging]
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: |
          echo "Deploying image tag: ${{ needs.build.outputs.image-tag }}"
          # kubectl set image deployment/web app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.build.outputs.image-tag }}
          # kubectl rollout status deployment/web

GitLab CI

GitLab CI is the built-in CI/CD system for GitLab. Pipelines are defined in .gitlab-ci.yml at the repository root and executed by GitLab runners. Jobs are organized into stages that run sequentially, with jobs within each stage running in parallel.

Pipeline Structure

The .gitlab-ci.yml file defines stages, jobs, and their execution order.

# Standardeinstellungen, die auf alle Jobs angewendet werden
default:
  image: node:20-alpine
  before_script:
    - npm ci --cache .npm
    - npm ci
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
  artifacts:
    expire_in: 7 days

# Globale Variablen
variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"
  DOCKER_DRIVER: overlay2

# Stages werden nacheinander ausgeführt; Jobs innerhalb einer Stage laufen parallel
stages:
  - lint
  - test
  - build
  - deploy

lint:
  stage: lint
  script:
    - npm run lint
    - npm run typecheck

test:unit:
  stage: test
  script:
    - npm run test:unit -- --coverage
  coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/'
  artifacts:
    when: always
    paths:
      - coverage/

test:integration:
  stage: test
  script:
    - npm run test:integration
needs: ["lint"]

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 30 days

deploy:staging:
  stage: deploy
  script:
    - echo "Deploying to staging..."
  environment: staging
  only:
    - main

deploy:production:
  stage: deploy
  script:
    - echo "Deploying to production..."
  environment: production
  when: manual
  only:
    - main

Runners

GitLab runners execute jobs. Use shared runners, group runners, or specific project runners with tags.

# Gemeinsame Runner verwenden (für alle Projekte verfügbar)
job-on-shared-runner:
  stage: test
  script:
    - echo "Running on shared runner"

# Einen spezifischen Runner über Tags verwenden
job-on-specific-runner:
  stage: test
  tags:
    - docker
    - linux
  script:
    - echo "Running on tagged runner"

# Einen selbst gehosteten Runner mit benutzerdefiniertem Docker-Image verwenden
job-on-custom-runner:
  stage: deploy
  tags:
    - production
    - kubernetes
  image: alpine:latest
  script:
    - kubectl apply -f k8s/

Variables and Secrets

Define variables at multiple scopes with different protection levels.

# Globale Variablen (sichtbar in den Pipeline-Logs — nicht für Secrets geeignet)
variables:
  APP_NAME: myapp
  APP_ENV: production
  DEPLOY_REGION: us-east-1

# Variablen vom Typ "File" (nützlich für Zertifikate, Konfigurationsdateien)
variables:
  KUBE_CONFIG: # In der GitLab UI als Typ "File" festlegen
  SSL_CERT: # In der GitLab UI als Typ "File" festlegen

build:
  stage: build
  variables:
    # Override auf Job-Ebene
    NODE_ENV: production
  script:
    # CI/CD-Variablen (festgelegt unter Settings > CI/CD > Variables)
    # Protected: nur auf geschützten Branches/Tags verfügbar
    # Masked: in den Job-Logs ausgeblendet
    # Typ: Variable oder File
    - echo "Deploying $APP_NAME to $DEPLOY_REGION"
    - echo "DB host: $DB_HOST" # Variablentyp
    - echo "Config at $APP_CONFIG" # Dateityp (Pfad zur temporären Datei)
    - cat "$APP_CONFIG" # Dateityp-Variable auslesen
    - |
      # Vordefinierte CI/CD-Variablen verwenden
      echo "Pipeline ID: $CI_PIPELINE_ID"
      echo "Commit SHA: $CI_COMMIT_SHA"
      echo "Branch: $CI_COMMIT_BRANCH"
      echo "Default branch: $CI_DEFAULT_BRANCH"
      echo "Project path: $CI_PROJECT_PATH"
      echo "Runner tags: $CI_RUNNER_TAGS"

deploy:
  stage: deploy
  script:
    # Zugriff auf geschützte Variablen (nur auf geschützten Branches)
    - echo "$PRODUCTION_DB_PASSWORD" | docker login -u admin --password-stdin
  environment:
    name: production
  only:
    - main # Geschützter Branch — kann auf geschützte Variablen zugreifen

Artifacts and Cache

Persist files between jobs (artifacts) and speed up jobs by caching dependencies (cache).

# Artefakte definieren — Dateien, die zwischen Stages übergeben werden
build:
  stage: build
  script:
    - npm run build
artifacts:
    name: "build-$CI_COMMIT_SHORT_SHA"
    paths:
      - dist/
      - build-report.json
    exclude:
      - dist/**/*.map
    expire_in: 2 weeks
    when: on_success # on_success (Standard), on_failure, always
    expose_as: "Build Output" # Label für den Download-Link in der UI

test:
  stage: test
  needs: [build] # Startet sofort nach Abschluss von build (wartet nicht auf die Stage-Reihenfolge)
  script:
    - npm run test
  artifacts:
    when: always # Upload auch bei fehlgeschlagenen Tests
    paths:
      - test-results/
    reports:
      # JUnit Testbericht (zeigt Ergebnisse im MR an)
      junit: test-results/junit.xml
      # Code-Coverage-Bericht
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    # Artifact-Download
  dependencies:
    - build # Nur Artifacts aus dem build-Job herunterladen

# Cache — beschleunigt die Job-Ausführung
.cache-template: &cache-npm
  cache:
    key:
      files:
        - package-lock.json
      prefix: npm
    paths:
      - .npm/
    policy: pull-push # Standard: Cache lesen und aktualisieren

install:
  stage: .pre
  <<: *cache-npm
  script:
    - npm ci

test:unit:
  stage: test
  <<: *cache-npm
  cache:
    <<: *cache-npm
    policy: pull # Nur Cache lesen, nicht aktualisieren
  script:
    - npm run test:unit

# Docker Layer Caching
docker-build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  cache:
    key: "$CI_JOB_NAME"
    paths:
      - .docker-cache/
  before_script:
    - docker load -i .docker-cache/build.tar || true
  script:
    - docker build --cache-from myapp:latest -t myapp:$CI_COMMIT_SHA .
    - docker save myapp:$CI_COMMIT_SHA -o .docker-cache/build.tar

Rules, Only/Except, and Workflow

Control when jobs run using rules (preferred) or the legacy only/except keywords.

# Moderne Rules-Syntax (bevorzugt)
test:
  script: npm test
  rules:
    # Ausführung auf dem main-Branch
    - if: $CI_COMMIT_BRANCH == "main"
    # Ausführung in Merge-Request-Pipelines
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Ausführung in geplanten Pipelines (Schedules)
    - if: $CI_PIPELINE_SOURCE == "schedule"
      variables:
        RUN_SLOW_TESTS: "true"
    # Ausführung, wenn eine bestimmte Datei geändert wurde
    - changes:
        - src/**/*
        - package.json
    # Ausführung bei Tags, die einem Muster entsprechen
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
    # Manuelle Ausführung
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual
      allow_failure: true
    # Standard-Fallback (nicht ausführen, wenn keine der obigen Bedingungen zutrifft)
    - when: never

# Komplexe Rules mit Bedingungen
deploy:
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      exists:
        - Dockerfile
      changes:
        - src/**/*
      variables:
        DEPLOY_ENV: production
    - if: $CI_COMMIT_BRANCH == "develop"
      variables:
        DEPLOY_ENV: staging
# Nur Legacy only/except (wird weiterhin unterstützt)
legacy-job:
  script: echo "Legacy syntax"
  only:
    - main
    - develop
    - /^release\/.*$/
    - merge_requests
    - tags
    - schedules
    - api
    - web # Manueller Trigger über die UI
  except:
    - feature/*
    - /^hotfix\/.*/

Environments

Define deployment environments with tracking, URLs, and protection rules.

variables:
  KUBE_NAMESPACE: ""

deploy:staging:
  stage: deploy
  script:
    - echo "Deploying to staging..."
    - kubectl apply -f k8s/staging/
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop:staging # Trigger für Cleanup-Job
  only:
    - develop

# Eine Umgebung stoppen/löschen
stop:staging:
  stage: deploy
  script:
    - echo "Stopping staging environment..."
    - kubectl delete namespace staging
  environment:
    name: staging
    action: stop # Markiert die Umgebung als gestoppt
  when: manual

deploy:production:
  stage: deploy
  script:
    - echo "Deploying to production..."
    - kubectl apply -f k8s/production/
  environment:
    name: production
    url: https://example.com
    # Automatisches Stoppen nach 30 Tagen Inaktivität (erfordert Premium+)
    auto_stop_in: 30 days
  only:
    - main

deploy:review:
  stage: deploy
  script:
    - echo "Deploying review app for $CI_MERGE_REQUEST_IID..."
    - kubectl create namespace review-$CI_MERGE_REQUEST_IID || true
    - kubectl apply -f k8s/review/ -n review-$CI_MERGE_REQUEST_IID
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop:review
  only:
    - merge_requests

stop:review:
  stage: deploy
  script:
    - kubectl delete namespace review-$CI_MERGE_REQUEST_IID
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual
  only:
    - merge_requests

Manual Jobs

Require human intervention before execution. Useful for production deployments and destructive operations.

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script: npm run build
  artifacts:
    paths: [dist/]

test:
  stage: test
  script: npm test

# Manueller Job — blockiert, bis ein Benutzer auf "Play" klickt
deploy:production:
  stage: deploy
  script:
    - ./deploy.sh production
  environment:
    name: production
  when: manual
  # Erlaubt, dass die Pipeline erfolgreich ist, auch wenn dieser Job übersprungen wird
  allow_failure: false

# Manueller Job mit optionaler Ausführung
deploy:canary:
stage: deploy
  script:
    - ./deploy-canary.sh
  when: manual
  allow_failure: true # Pipeline gilt als bestanden, auch wenn der Job übersprungen wurde

# Manueller Job, der nur auf main ausgelöst wird
cleanup:
  stage: deploy
  script:
    - ./cleanup.sh
  when: manual
  only:
    - main
  allow_failure: true

Include, Extend, and Templates

Reuse configuration with include, share settings with extends, and create job templates.

# Einbinden externer Konfigurationsdateien
include:
  # Datei im selben Repository
  - local: .gitlab/ci/rules.yml
  # Datei in einem anderen Repository
  - project: myorg/shared-pipelines
    ref: main
    file: /templates/nodejs.yml
  # Remote-URL
  - remote: https://example.com/ci-templates/base.yml
  # Template aus dem CI/CD-Katalog von GitLab (GitLab 16+)
  - component: gitlab.com/gitlab-org/components/dotnet/dotnet-build@1.2.0
    inputs:
      stage: build
      dotnet_version: "8.0.x"

# YAML-Anker und Aliase
.cache-npm: &cache-npm
  cache:
    key:
      files: [package-lock.json]
    paths: [.npm/]

.install-deps: &install-deps
  before_script:
    - npm ci --cache .npm

# Templates erweitern
.test-base:
  <<: [*cache-npm, *install-deps]
  stage: test
  image: node:20-alpine

test:unit:
  extends: .test-base
  script:
    - npm run test:unit

test:integration:
  extends: .test-base
  script:
    - npm run test:integration
  services:
    - name: postgres:15
      alias: db

# Versteckte Job-Templates (Präfix mit .) werden nicht eigenständig ausgeführt
.docker-base:
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

build:api:
  extends: .docker-base
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHA ./apps/api
    - docker push $CI_REGISTRY_IMAGE/api:$CI_COMMIT_SHA

build:web:
  extends: .docker-base
  stage: build
  script:
    - docker build -t $CI_REGISTRY_IMAGE/web:$CI_COMMIT_SHA ./apps/web
    - docker push $CI_REGISTRY_IMAGE/web:$CI_COMMIT_SHA

Merge Request Pipelines

Special pipeline behavior for merge requests including MR-specific variables and workflow rules.

# Steuerung, welche Pipelines für MRs vs. Branch-Pushes ausgeführt werden
workflow:
  rules:
    # Merge-Request-Pipelines für Branches mit offenen MRs ausführen
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Branch-Pipelines für den Default-Branch ausführen
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    # Tag-Pipelines ausführen
    - if: $CI_COMMIT_TAG
    # Geplante Pipelines ausführen
    - if: $CI_PIPELINE_SOURCE == "schedule"
    # Über API/Web ausgelöste Pipelines ausführen
    - if: $CI_PIPELINE_SOURCE == "api"
    - if: $CI_PIPELINE_SOURCE == "web"
    # Keine Branch-Pipelines für Feature-Branches ausführen (stattdessen MR-Pipeline nutzen)
    - when: never

variables:
  # In MR-Pipelines nur den MR-Diff bauen
  GET_SOURCES_ATTEMPT: "3"

test:
stage: test
  script:
    - echo "MR Title: $CI_MERGE_REQUEST_TITLE"
    - echo "MR Source: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
    - echo "MR Target: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - echo "MR IID: $CI_MERGE_REQUEST_IID"
    - npm run test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

lint:
  stage: test
  script:
    - npm run lint
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      # Nur geänderte Dateien linten
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# Nur in Merge-Request-Pipelines ausführen, nicht in Branch-Pipelines
review-deploy:
  stage: deploy
  script:
    - echo "Deploying review app for MR !${CI_MERGE_REQUEST_IID}"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual

Complete Real-World Example: Multi-Service Docker Pipeline

# .gitlab-ci.yml — Multi-Service Docker CI/CD

include:
  - local: .gitlab/ci/variables.yml

default:
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"

variables:
  DOCKER_TLS_CERTDIR: "/certs"

stages:
  - validate
  - test
  - build
  - deploy

# ─── Validate ───────────────────────────────────────────

lint:
  stage: validate
  image: node:20-alpine
  before_script:
    - npm ci
  script:
    - npm run lint
    - npm run typecheck
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# ─── Test ───────────────────────────────────────────────

test:unit:
  stage: test
  image: node:20-alpine
  services:
    - name: postgres:15-alpine
      alias: postgres
  variables:
    POSTGRES_DB: testdb
    POSTGRES_USER: testuser
    POSTGRES_PASSWORD: testpass
    DATABASE_URL: postgresql://testuser:testpass@postgres:5432/testdb
  before_script:
    - npm ci
    - npx prisma migrate deploy
  script:
    - npm run test:unit -- --ci --coverage
  coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/'
  artifacts:
    when: always
    reports:
      junit: test-results/junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# ─── Build ──────────────────────────────────────────────

.docker-build:
  stage: build
  variables:
    IMAGE: $CI_REGISTRY_IMAGE/$SERVICE
  script:
    - docker pull $IMAGE:latest || true
    - docker build
      --cache-from $IMAGE:latest
      --tag $IMAGE:$CI_COMMIT_SHA
      --tag $IMAGE:latest
      -f apps/$SERVICE/Dockerfile
      apps/$SERVICE
    - docker push $IMAGE:$CI_COMMIT_SHA
    - docker push $IMAGE:latest

build:api:
  extends: .docker-build
  variables:
SERVICE: api
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [apps/api/**/*]

build:web:
  extends: .docker-build
  variables:
    SERVICE: web
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [apps/web/**/*]

build:worker:
  extends: .docker-build
  variables:
    SERVICE: worker
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [apps/worker/**/*]

# ─── Deploy ─────────────────────────────────────────────

.deploy-k8s:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl config use-context $KUBE_CONTEXT
    - kubectl set image deployment/$SERVICE $SERVICE=$CI_REGISTRY_IMAGE/$SERVICE:$CI_COMMIT_SHA -n $KUBE_NAMESPACE
    - kubectl rollout status deployment/$SERVICE -n $KUBE_NAMESPACE --timeout=300s

deploy:staging:
  extends: .deploy-k8s
  variables:
    KUBE_CONTEXT: staging
    KUBE_NAMESPACE: staging
    SERVICE: api
  environment:
    name: staging
    url: https://staging-api.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy:production:
  extends: .deploy-k8s
  variables:
    KUBE_CONTEXT: production
    KUBE_NAMESPACE: production
    SERVICE: api
  environment:
    name: production
    url: https://api.example.com
  when: manual
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Schneller Vergleich

Nächste Schritte

• Docker CLI Cheat Sheet — Container-Images erstellen und verwalten
• Kubernetes kubectl Cheat Sheet — Container im großen Stil orchestrieren
• Helm CLI Cheat Sheet — Kubernetes-Anwendungen paketieren und deployen
• Terraform Cheat Sheet — Referenz für Infrastructure as Code

Ressourcen & Verwandte Plattformen

• tobias-weiss.org - Weitere Cheat Sheets, Artikel und Shop-Produkte
• graphwiz.ai - KI, Knowledge Graphs und agentenbasierte Entwicklung
• courses.graphwiz.ai - Interaktive Übungsprüfungen und Lernleitfäden
• ki-kompetenz-training.org - EU AI Act konforme KI-Kompetenztrainings

Verwandte Cheat Sheets

• Docker CLI Cheat Sheet - Containerisieren Sie Ihre Pipelines
• Kubernetes Cheat Sheet - Deployment auf K8s