MR Staging – Review Apps für Merge Requests

Die mr-staging-Komponente automatisiert das Deployment von Merge Requests auf einen Staging-Server. Damit lassen sich Feature-Branches als eigenständige Review-Umgebungen bereitstellen, bevor sie in den Hauptbranch gemergt werden.

Diese Komponente wird vor allem im Development-/Master-Workflow eingesetzt.

Funktionsweise

1. Ein Merge Request wird mit dem Label deploy-review versehen
2. Die Pipeline baut Docker-Image(s) aus den definierten Dockerfiles
3. Die Images werden in die GitLab Container Registry gepusht
4. Per Docker Compose wird die Anwendung auf dem Staging-Server deployed
5. Eine dynamische URL wird basierend auf dem Branch-Namen generiert
6. Beim Merge oder manuell kann die Umgebung wieder aufgeräumt werden

Voraussetzungen

Staging-Server

• GitLab Runner mit dem konfigurierten Tag (Standard: staging01) registriert
• Docker und Docker Compose v2 installiert
• Netzwerkzugang zur GitLab Container Registry
• Reverse Proxy (z.B. Traefik) für Host-basiertes Routing konfiguriert
• Deploy-Verzeichnis beschreibbar durch Runner-User

DNS

• Wildcard-DNS-Eintrag: *.<domain_suffix> zeigt auf den Staging-Server

GitLab-Projekt

• Ein oder mehrere Dockerfiles (Standard: ./Dockerfile)
• Eine docker-compose.yml mit den exportierten Umgebungsvariablen
• GitLab Container Registry aktiviert
• Stages build und deploy in der .gitlab-ci.yml definiert
• Das Label deploy-review im Projekt erstellt

Einrichtung

Wichtig

Das Label deploy-review muss im Merge Request gesetzt sein, damit ein Staging-Build ausgelöst wird. Ohne dieses Label wird kein Deployment durchgeführt.

Schritt 1: Component einbinden

stages:
  - build
  - deploy

include:
  - component: git.styrion.net/iteas/gitlab-components/mr-staging@main
    inputs:
      domain_suffix: "feature.your-domain.de"

Schritt 2: docker-compose.yml vorbereiten

Die Komponente exportiert folgende Umgebungsvariablen, die in der docker-compose.yml verwendet werden können:

Variable	Beispiel	Beschreibung
CI_REGISTRY_IMAGE	registry.example.com/group/project	Registry-Pfad für Images
CI_COMMIT_REF_SLUG	feature-login-page	URL-sicherer Branch-Name
COMPOSE_PROJECT_NAME	myapp_feature-login-page	Docker Compose Projektname
REVIEW_DOMAIN	feature-login-page.feature.your-domain.de	Domain der Review-App
DOMAIN_SUFFIX	feature.your-domain.de	Basis-Domain für alle Services

Minimale docker-compose.yml mit Traefik:

services:
  app:
    image: ${CI_REGISTRY_IMAGE}/app:${CI_COMMIT_REF_SLUG}
    restart: always
    networks:
      - traefik_public
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.rule=Host(`${REVIEW_DOMAIN}`)"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.entrypoints=websecure"
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}.tls=true"
      - "traefik.docker.network=traefik_public"
      - "traefik.http.services.${COMPOSE_PROJECT_NAME}.loadbalancer.server.port=80"

networks:
  traefik_public:
    external: true

Schritt 3: Label im Merge Request setzen

1. Merge Request erstellen
2. Label deploy-review zum MR hinzufügen
3. Die Pipeline wird automatisch ausgelöst und deployed

Konfigurationsoptionen

Input	Beschreibung	Pflicht	Standard
domain_suffix	Basis-Domain für Review-App-URLs	Ja	-
stage_build	Pipeline-Stage für den Build-Job	Nein	build
stage_deploy	Pipeline-Stage für Deploy- und Stop-Jobs	Nein	deploy
docker_builds	Docker-Images (Format: IMAGE_NAME=DOCKERFILE_PATH, eine pro Zeile)	Nein	app=./Dockerfile
build_extra_args	Zusätzliche docker build Flags (z.B. --secret, --build-arg)	Nein	(leer)
mr_label	MR-Label das das Deployment auslöst	Nein	deploy-review
runner_tag	GitLab Runner Tag für den Staging-Server	Nein	staging01
compose_file	Pfad zur docker-compose.yml relativ zum Projekt-Root	Nein	docker-compose.yml
deploy_base_dir	Basis-Verzeichnis am Staging-Server für Deployments	Nein	/opt/staging_docker

Erzeugte Jobs

Die Komponente erstellt drei Jobs:

mr-staging:build

• Baut alle konfigurierten Docker-Images
• Pusht sie in die GitLab Container Registry mit dem Tag <registry>/<image-name>:<branch-slug>
• Läuft auf Runner build-ubuntu-2404-64

mr-staging:deploy

• Erstellt Deployment-Verzeichnis: <deploy_base_dir>/<project-name>/<branch-slug>/
• Kopiert die docker-compose.yml auf den Staging-Server
• Exportiert alle Umgebungsvariablen und startet die Container
• Erstellt ein dynamisches GitLab-Environment mit URL https://<branch-slug>.<domain_suffix>

mr-staging:stop

• Stoppt und entfernt alle Container inkl. Volumes (docker compose down --volumes)
• Räumt das Deployment-Verzeichnis auf
• Manuell auslösbar oder automatisch beim Merge

Gelöschte Merge Requests

Wird ein Merge Request gelöscht statt gemergt, wird der Stop-Job nicht automatisch ausgeführt. Die Container und Dateien bleiben auf dem Staging-Server bestehen.

In diesem Fall muss das Environment manuell aufgeräumt werden:

1. Im Projekt zu Operate → Environments navigieren
2. Das betroffene Review-Environment suchen (z.B. review/<branch-name>)
3. Über die Schaltfläche Stop das Environment manuell stoppen

Dadurch wird der mr-staging:stop-Job nachträglich ausgelöst und die Container sowie das Deployment-Verzeichnis auf dem Staging-Server werden entfernt.

Erweiterte Konfiguration

Mehrere Docker-Images

include:
  - component: git.styrion.net/iteas/gitlab-components/mr-staging@main
    inputs:
      domain_suffix: "staging.example.com"
      docker_builds: |
        app=./Dockerfile
        worker=./docker/Dockerfile.worker
        nginx=./docker/Dockerfile.nginx

Multi-Service URLs

Bei mehreren Services kann DOMAIN_SUFFIX für individuelle Subdomains verwendet werden:

services:
  app:
    image: ${CI_REGISTRY_IMAGE}/app:${CI_COMMIT_REF_SLUG}
    labels:
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}-app.rule=Host(`app-${CI_COMMIT_REF_SLUG}.${DOMAIN_SUFFIX}`)"

  api:
    image: ${CI_REGISTRY_IMAGE}/api:${CI_COMMIT_REF_SLUG}
    labels:
      - "traefik.http.routers.${COMPOSE_PROJECT_NAME}-api.rule=Host(`api-${CI_COMMIT_REF_SLUG}.${DOMAIN_SUFFIX}`)"

Jobs erweitern mit before_script

Alle drei Jobs können per before_script erweitert werden, ohne die Hauptlogik zu überschreiben:

Build-Credentials setzen:

mr-staging:build:
  before_script:
    - export COMPOSER_AUTH='{"http-basic":{"git.styrion.net":{"username":"'$GITLAB_USER'","password":"'$GITLAB_PASS'"}}}'

Zusätzliche Variablen beim Deploy:

mr-staging:deploy:
  before_script:
    - export APP_VERSION=$CI_COMMIT_SHORT_SHA
    - export EXTRA_CONFIG="some-value"

Diese Variablen sind dann in der docker-compose.yml als ${APP_VERSION}, ${EXTRA_CONFIG} etc. verfügbar.

Vollständiges Beispiel

stages:
  - build
  - deploy

include:
  - component: git.styrion.net/iteas/gitlab-components/mr-staging@main
    inputs:
      domain_suffix: "feature.your-domain.de"
      docker_builds: |
        app=./Dockerfile
        worker=./docker/Dockerfile.worker
      build_extra_args: "--secret id=composer_auth,env=COMPOSER_AUTH"

# Build-Job mit Composer-Credentials erweitern
mr-staging:build:
  before_script:
    - export COMPOSER_AUTH='{"http-basic":{"git.styrion.net":{"username":"'$GITLAB_USER'","password":"'$GITLAB_PASS'"}}}'

# Deploy-Job mit zusätzlichen Variablen
mr-staging:deploy:
  before_script:
    - export APP_VERSION=$CI_COMMIT_SHORT_SHA