GitLab CI CD Pipeline einrichten 2025 – Vollständige Anleitung für Einsteiger
Eine GitLab CI CD Pipeline automatisiert das Testen, Bauen und Deployen von Software – bei jedem Code-Commit automatisch. Was früher Stunden manueller Arbeit erforderte, erledigt eine gut konfigurierte GitLab CI CD Pipeline in Minuten. Dieser Leitfaden zeigt Ihnen, wie Sie von Null an Ihre erste produktive Pipeline einrichten.
Als IT-Dienstleister betreuen wir GitLab-Installationen für Unternehmenskunden und haben hunderte von GitLab CI CD Pipeline Konfigurationen erstellt. Diese Anleitung gibt praktisches Wissen weiter.
Inhaltsverzeichnis
- GitLab CI CD Pipeline: Grundkonzepte
- Die .gitlab-ci.yml Datei
- GitLab CI CD Pipeline: Stages und Jobs
- Variables und Secrets
- GitLab CI CD Pipeline: Runner einrichten
- Artefakte und Cache
- GitLab CI CD Pipeline: Praxisbeispiel PHP/WordPress
- Docker-Images in der Pipeline bauen
- GitLab CI CD Pipeline: Deployment auf Server
- Conditional Pipelines und Rules
- GitLab CI CD Pipeline: Environments
- Security Scanning
- GitLab CI CD Pipeline: Best Practices
- Häufige Fehler
- Fazit
1. GitLab CI CD Pipeline: Grundkonzepte
Bevor wir die erste GitLab CI CD Pipeline konfigurieren, die wichtigsten Begriffe:
- Pipeline: Die übergeordnete Einheit – alle Jobs die bei einem Trigger (Push, Merge Request, Schedule) ausgeführt werden
- Stage: Eine Phase der Pipeline (z. B. build, test, deploy). Stages laufen sequenziell.
- Job: Eine konkrete Aufgabe innerhalb einer Stage. Jobs einer Stage laufen parallel.
- Runner: Die Maschine (physisch oder virtuell) die Jobs ausführt
- Artifact: Dateien die ein Job produziert und die nachfolgende Jobs nutzen können
2. Die .gitlab-ci.yml Datei
Die gesamte GitLab CI CD Pipeline wird durch eine einzige Datei definiert: .gitlab-ci.yml im Root-Verzeichnis des Repositories. GitLab erkennt sie automatisch.
# Minimale .gitlab-ci.yml:
stages:
- build
- test
- deploy
build-job:
stage: build
image: php:8.2-cli
script:
- composer install --no-dev
- echo "Build abgeschlossen"
test-job:
stage: test
image: php:8.2-cli
script:
- vendor/bin/phpunit
deploy-job:
stage: deploy
script:
- echo "Deployment..."
only:
- main
3. GitLab CI CD Pipeline: Stages und Jobs im Detail
Eine gut strukturierte GitLab CI CD Pipeline hat klare Stages mit definierten Verantwortlichkeiten:
stages:
- validate # Code-Qualität, Syntax-Prüfung
- test # Unit-Tests, Integration-Tests
- build # Docker-Images, Pakete bauen
- deploy # Staging, Produktion
# Stage: validate
php-lint:
stage: validate
image: php:8.2-cli
script:
- find . -name "*.php" -not -path "./vendor/*" -exec php -l {} ;
allow_failure: false # Fehler hier bricht die Pipeline ab
phpcs:
stage: validate
image: php:8.2-cli
before_script:
- composer global require squizlabs/php_codesniffer
script:
- phpcs --standard=PSR12 src/
# Stage: test
phpunit:
stage: test
image: php:8.2-cli
services:
- mysql:8.0 # Datenbank als Service für Tests
variables:
MYSQL_DATABASE: test_db
MYSQL_ROOT_PASSWORD: test
DB_HOST: mysql
before_script:
- composer install --no-progress
- cp .env.testing .env
script:
- vendor/bin/phpunit --coverage-text
coverage: '/Lines:s+(d+.d+)%/' # Coverage aus Output extrahieren
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage.xml
4. Variables und Secrets in der GitLab CI CD Pipeline
Passwörter und API-Keys gehören nie in die .gitlab-ci.yml. Die GitLab CI CD Pipeline nutzt CI/CD-Variablen die verschlüsselt gespeichert werden.
Konfiguration: GitLab → Projekt → Einstellungen → CI/CD → Variables
| Variable | Typ | Verwendung |
|---|---|---|
| SSH_PRIVATE_KEY | File / Masked | SSH-Schlüssel für Server-Deployment |
| PRODUCTION_SERVER | Variable | Hostname des Produktionsservers |
| DB_PASSWORD_PROD | Variable / Masked | Datenbankpasswort Produktion |
| DOCKER_REGISTRY_TOKEN | Variable / Masked | Token für Container Registry |
# Variablen in der Pipeline nutzen:
deploy:
script:
- echo "$SSH_PRIVATE_KEY" > /tmp/key && chmod 600 /tmp/key
- ssh -i /tmp/key user@$PRODUCTION_SERVER "cd /var/www && git pull"
5. GitLab CI CD Pipeline: Runner einrichten
Für die GitLab CI CD Pipeline gibt es zwei Runner-Varianten: GitLab.com Shared Runners (kostenlos bis zu einem monatlichen Limit) oder eigene Self-Hosted Runner für mehr Kontrolle und Performance.
Self-Hosted Runner auf Ubuntu installieren
# Runner installieren:
curl -L --output /usr/local/bin/gitlab-runner
"https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"
chmod +x /usr/local/bin/gitlab-runner
useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
gitlab-runner start
# Runner registrieren (Token aus GitLab → Einstellungen → CI/CD → Runner):
gitlab-runner register
--url https://gitlab.ihreseite.de
--registration-token IHR_REGISTRATION_TOKEN
--executor docker
--docker-image alpine:latest
--description "Docker Runner Produktion"
--tag-list "docker,production,linux"
Runner-Executor: Docker vs Shell
- Docker-Executor (empfohlen): Jeder Job läuft in einem frischen Container – sauber, reproduzierbar, isoliert
- Shell-Executor: Jobs laufen direkt auf dem Runner-Host – schneller aber weniger isoliert, Nebeneffekte möglich
6. Artefakte und Cache
Artefakte und Cache sind wichtige Performance-Hebel für die GitLab CI CD Pipeline:
build-frontend:
stage: build
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/ # Diese Dateien zwischen Stages weitergeben
expire_in: 1 week # Artefakte nach 1 Woche löschen
cache:
key: node-${CI_COMMIT_REF_SLUG}
paths:
- node_modules/ # Cache für schnellere Folge-Builds
Unterschied: Cache wird zwischen Pipeline-Runs gespeichert (npm-Module nicht neu herunterladen). Artefakte werden zwischen Stages derselben Pipeline weitergegeben (Build-Output für Deploy-Stage).
7. GitLab CI CD Pipeline: Vollständiges PHP-Beispiel
image: php:8.2-fpm
stages: [validate, test, build, deploy]
variables:
COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"
cache:
paths: [.composer-cache/, vendor/]
# ── validate ──────────────────────────────────
php-lint:
stage: validate
script: find . -name "*.php" -not -path "./vendor/*" -exec php -l {} ;
# ── test ───────────────────────────────────────
phpunit:
stage: test
services: [mysql:8.0]
variables:
MYSQL_DATABASE: testdb
MYSQL_ROOT_PASSWORD: test
before_script:
- composer install --no-progress
- cp .env.ci .env
script: vendor/bin/phpunit --coverage-text
# ── build ──────────────────────────────────────
build-docker:
stage: build
image: docker:24
services: [docker:24-dind]
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 build -t $CI_REGISTRY_IMAGE:latest .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
- docker push $CI_REGISTRY_IMAGE:latest
rules:
- if: $CI_COMMIT_BRANCH == "main"
# ── deploy ─────────────────────────────────────
deploy-staging:
stage: deploy
image: alpine:latest
before_script:
- apk add --no-cache openssh-client rsync
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | ssh-add -
- mkdir -p ~/.ssh && echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
script:
- rsync -avz --delete dist/ user@staging.tosmedia.de:/var/www/html/
environment:
name: staging
url: https://staging.tosmedia.de
rules:
- if: $CI_COMMIT_BRANCH == "main"
deploy-production:
stage: deploy
script:
- rsync -avz dist/ user@prod.tosmedia.de:/var/www/html/
environment:
name: production
url: https://tosmedia.de
rules:
- if: $CI_COMMIT_TAG # Nur bei Git-Tags deployen
when: manual # Manueller Bestätigung erforderlich
8. GitLab CI CD Pipeline: Conditional Rules
Die GitLab CI CD Pipeline bietet mächtige Rules für bedingtes Ausführen von Jobs:
# Nur ausführen wenn bestimmte Dateien geändert wurden:
backend-tests:
rules:
- changes:
- "src/**/*"
- "tests/**/*"
- composer.json
# Nur auf main-Branch oder bei Tags:
deploy-prod:
rules:
- if: $CI_COMMIT_BRANCH == "main"
- if: $CI_COMMIT_TAG =~ /^vd+.d+.d+$/
# Nie in Fork-Pipelines ausführen:
expensive-job:
rules:
- if: $CI_PROJECT_NAMESPACE == "tosmedia"
9. GitLab CI CD Pipeline: Best Practices
- Schnelle Pipelines: Lint- und Syntax-Checks zuerst (schlagen schnell fehl, sparen Zeit bei echten Fehlern)
- Parallelisierung: Unabhängige Jobs in dieselbe Stage – laufen parallel und sparen Zeit
- Cache sinnvoll nutzen: Abhängigkeiten (vendor/, node_modules/) cachen, Build-Outputs nicht
- Branches isolieren: Staging-Deployment nur auf main-Branch, Produktion nur bei Git-Tags
- Manuelles Deployment für Produktion:
when: manualverhindert versehentliche Deployments - Secrets rotieren: CI/CD-Variablen (SSH-Keys, Tokens) regelmäßig erneuern
10. Fazit: GitLab CI CD Pipeline
Eine gut konfigurierte GitLab CI CD Pipeline transformiert Ihren Entwicklungsprozess. Manuelle Deployments entfallen, Fehler werden früh entdeckt, Code-Qualität steigt und Releases werden vorhersehbarer. Der Einrichtungsaufwand amortisiert sich nach wenigen Wochen.
TOSMedia installiert GitLab und konfiguriert CI/CD-Pipelines für Entwicklungsteams. Ob einfache PHP-Pipelines oder komplexe Multi-Service-Deployments – wir helfen.
GitLab CI CD Pipeline: Security Scanning
GitLab bietet in der Community Edition kostenlose Security-Scanner. Eine professionelle GitLab CI CD Pipeline sollte diese nutzen:
include:
- template: Security/SAST.gitlab-ci.yml # Static Application Security Testing
- template: Security/Secret-Detection.gitlab-ci.yml # Findet Secrets im Code
stages: [test, security, deploy]
# SAST und Secret-Detection werden automatisch ausgeführt
# Ergebnisse erscheinen im Merge Request als Security-Report
SAST (Static Application Security Testing) analysiert Ihren Code auf bekannte Schwachstellen ohne die Anwendung auszuführen. Secret Detection findet versehentlich eingecheckte Passwörter, API-Keys und Zertifikate. Beide sind in GitLab CE kostenlos.
Dependency Scanning
include:
- template: Security/Dependency-Scanning.gitlab-ci.yml
dependency_scanning:
stage: security
variables:
DS_EXCLUDED_PATHS: "vendor,node_modules"
GitLab CI CD Pipeline: Notifications und Alerting
Eine GitLab CI CD Pipeline die still scheitert ist wertlos. Konfigurieren Sie Benachrichtigungen:
E-Mail-Benachrichtigungen
GitLab sendet automatisch E-Mails bei fehlgeschlagenen Pipelines. Konfigurierbar unter: Benutzereinstellungen → Benachrichtigungen → Pipeline-Benachrichtigungen
Mattermost/Slack Integration
stages: [test, notify]
notify-success:
stage: notify
image: curlimages/curl:latest
script:
- |
curl -X POST $MATTERMOST_WEBHOOK -H "Content-Type: application/json" -d "{"text": "✅ Pipeline erfolgreich: $CI_PROJECT_NAME ($CI_COMMIT_REF_NAME)"}"
rules:
- if: $CI_PIPELINE_STATUS == "success"
when: on_success
notify-failure:
stage: notify
image: curlimages/curl:latest
script:
- |
curl -X POST $MATTERMOST_WEBHOOK -H "Content-Type: application/json" -d "{"text": "❌ Pipeline fehlgeschlagen: $CI_PROJECT_NAME - $CI_JOB_URL"}"
when: on_failure
GitLab CI CD Pipeline: Scheduled Pipelines
Manche Aufgaben sollen regelmäßig laufen, nicht bei jedem Commit. Die GitLab CI CD Pipeline unterstützt geplante Ausführungen:
Konfiguration unter CI/CD → Schedules → New Schedule:
- Tägliche Dependency-Checks: jeden Morgen um 6 Uhr
- Wöchentliche Sicherheits-Scans: jeden Montag
- Monatliche Performance-Tests: am ersten des Monats
# In .gitlab-ci.yml nur bei Schedule-Trigger ausführen:
weekly-security-scan:
stage: security
script:
- vendor/bin/security-checker security:check
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"
GitLab CI CD Pipeline: Multi-Projekt-Pipelines
In größeren Setups triggert eine GitLab CI CD Pipeline Pipelines in anderen Projekten:
trigger-frontend:
stage: deploy
trigger:
project: tosmedia/frontend
branch: main
strategy: depend # Warte auf Downstream-Pipeline
trigger-docs:
stage: deploy
trigger:
project: tosmedia/documentation
strategy: depend
GitLab CI CD Pipeline: Performance optimieren
Langsame Pipelines nerven Entwickler und verlangsamen den Entwicklungsprozess. So optimieren Sie Ihre GitLab CI CD Pipeline:
Parallele Jobs
test:
stage: test
parallel:
matrix:
- PHP_VERSION: ["8.1", "8.2", "8.3"] # Testet alle 3 Versionen parallel
image: php:${PHP_VERSION}-cli
script:
- composer install --no-progress
- vendor/bin/phpunit
Interruptible Pipelines
# Ältere Pipelines für denselben Branch abbrechen wenn neue gestartet wird:
workflow:
rules:
- if: $CI_COMMIT_BRANCH
auto_cancel_pending_pipelines:
on_new_commit: interruptible
test-job:
interruptible: true # Dieser Job kann unterbrochen werden
Caching optimieren
cache:
key:
files:
- composer.lock # Cache-Key basiert auf Lock-File
- package-lock.json
paths:
- vendor/
- node_modules/
policy: pull-push # pull: nur lesen, push-pull: lesen und aktualisieren
GitLab CI CD Pipeline: Self-Hosted GitLab absichern
Wenn Sie GitLab selbst hosten, sind Sicherheitsaspekte der GitLab CI CD Pipeline besonders wichtig:
- Runner-Isolation: Produktions-Runner sollten keinen Zugang zu anderen Infrastruktur-Komponenten haben als nötig
- Privileged Mode vermeiden: Docker-in-Docker benötigt privileged=true – das ist ein Sicherheitsrisiko. Alternative: Kaniko oder Buildah für Image-Builds ohne privilegierten Zugang
- Job-Token begrenzen: Der CI_JOB_TOKEN hat standardmäßig Zugang zu Repository und Registry – begrenzen Sie ihn auf das Notwendige
- Protected Branches und Tags: Nur in Protected Branches/Tags können Secrets (Protected Variables) verwendet werden – nutzen Sie diesen Mechanismus für Produktions-Deployments
GitLab CI CD Pipeline: Vollständige Deployment-Strategien
Eine professionelle GitLab CI CD Pipeline unterstützt verschiedene Deployment-Strategien um Ausfallzeiten zu minimieren.
Blue-Green Deployment
Blue-Green-Deployment bedeutet: Sie betreiben zwei identische Produktionsumgebungen (Blue und Green). Der aktive Traffic läuft auf Blue. Das neue Release wird auf Green deployt und getestet. Dann wird der Traffic von Blue auf Green umgeschaltet – ohne Downtime. Bei Problemen ist ein sofortiger Rollback auf Blue möglich.
deploy-green:
stage: deploy
script:
- ssh deploy@prod "cd /var/www/green && git pull && composer install --no-dev"
- ssh deploy@prod "systemctl reload php8.2-fpm@green"
- echo "Green deployt, bereit für Switch"
environment:
name: green
url: https://green.ihreseite.de
switch-to-green:
stage: deploy
script:
- ssh deploy@prod "ln -sfn /var/www/green /var/www/current"
- ssh deploy@prod "systemctl reload nginx"
when: manual
needs: [deploy-green]
Rolling Deployments mit SSH auf mehrere Server
deploy-rolling:
stage: deploy
script:
- |
for SERVER in $PROD_SERVERS; do
echo "Deploying to $SERVER..."
ssh deploy@$SERVER "cd /var/www && git pull && composer install --no-dev && php artisan migrate --force"
echo "Deployment auf $SERVER abgeschlossen"
sleep 10 # Kurze Pause zwischen Servern
done
Canary Releases
Bei Canary-Releases wird das neue Release zunächst nur an einen kleinen Prozentsatz der Nutzer (z. B. 5 %) ausgeliefert. Bei guten Metriken wird der Anteil schrittweise erhöht. Die GitLab CI CD Pipeline kann das durch Feature-Flags oder Nginx-Weight-Routing umsetzen.
TOSMedia implementiert CI/CD-Pipelines mit GitLab für Entwicklungsteams aller Größen. Wir helfen Ihnen von der ersten GitLab CI CD Pipeline bis zu vollautomatischen Zero-Downtime-Deployments.
GitLab CI CD Pipeline: Für Ihr Team einrichten lassen
Eine gut konfigurierte GitLab CI CD Pipeline ist ein Wettbewerbsvorteil. Teams die CI/CD nutzen, deployen häufiger, mit weniger Fehlern und mehr Vertrauen in ihre Releases. Die Investition in eine professionelle GitLab CI CD Pipeline amortisiert sich typischerweise innerhalb von Wochen durch gesparte manuelle Deployment-Zeit und früh erkannte Bugs.
TOSMedia installiert GitLab (Self-Hosted oder GitLab.com), richtet Runner ein und konfiguriert CI/CD-Pipelines für Entwicklungsteams. Wir schulen Ihre Entwickler in GitLab CI/CD und stehen langfristig als Ansprechpartner für Pipeline-Optimierungen zur Verfügung.
Typische Projekte: WordPress-Plugins mit automatischen PHPUnit-Tests und FTP-Deployment, PHP-Anwendungen mit Docker-Image-Builds und Kubernetes-Deployment, statische Webseiten mit automatischem Build und CDN-Deployment. Kontaktieren Sie uns für eine kostenlose Erstberatung zu Ihrer GitLab CI CD Pipeline.
GitLab CI CD Pipeline: Zusammenfassung der wichtigsten Punkte
Die wichtigsten Erkenntnisse aus diesem Leitfaden zur GitLab CI CD Pipeline kompakt zusammengefasst: Eine .gitlab-ci.yml im Root des Repositories reicht für den Start. Stages strukturieren den Ablauf, Jobs führen konkrete Aufgaben aus. Variables und Secrets gehören nie in die Pipeline-Konfiguration direkt. Eigene Runner bieten mehr Kontrolle und Performance als Shared Runner. Cache spart Zeit bei Abhängigkeiten, Artefakte übertragen Dateien zwischen Stages. Rules und only/except steuern wann Jobs laufen.
Mit diesen Grundlagen können Sie Ihre erste produktive GitLab CI CD Pipeline einrichten. Beginnen Sie klein, mit einem einfachen Lint- und Test-Job, und erweitern Sie schrittweise. Jede Automatisierung spart dauerhaft Zeit und reduziert menschliche Fehler. Eine GitLab CI CD Pipeline die konsequent genutzt wird ist einer der größten Produktivitätsmultiplikatoren in der Softwareentwicklung.
Brauchen Sie Unterstützung bei der Einrichtung Ihrer ersten GitLab CI CD Pipeline? TOSMedia begleitet Entwicklungsteams von der GitLab-Installation bis zur vollautomatischen Deployment-Pipeline.
GitLab CI CD Pipeline: Integration mit externen Tools
Eine professionelle GitLab CI CD Pipeline arbeitet mit dem gesamten Tooling-Ökosystem zusammen. Hier die wichtigsten Integrationen aus der Praxis.
Jira-Integration
GitLab kann Jira-Issues automatisch schließen wenn der entsprechende Code deployt wird. Erwähnen Sie die Jira-Issue-ID im Commit-Message (Fixes PROJ-123), und GitLab markiert das Issue in Jira automatisch als gelöst. Konfiguration unter GitLab → Einstellungen → Integrationen → Jira.
Slack/Mattermost Pipeline-Status
Entwicklungsteams wollen sofort wissen wenn eine Pipeline fehlschlägt. Die Integration von Mattermost oder Slack in die GitLab CI CD Pipeline ist in wenigen Minuten konfiguriert. Unter GitLab → Einstellungen → Integrationen → Mattermost notifications aktivieren und den Webhook-URL eintragen. Ab sofort bekommt Ihr Team automatische Benachrichtigungen bei erfolgreichen und fehlgeschlagenen Pipelines.
SonarQube Code-Quality
SonarQube analysiert Code-Qualität, technische Schulden und Sicherheitsmuster. Die Integration in die GitLab CI CD Pipeline ist über das offizielle SonarQube-GitLab-Plugin möglich. Jeder Merge Request bekommt automatisch einen Quality-Gate-Status – grüner Daumen wenn der Code die Qualitätsstandards erfüllt, rotes X wenn nicht.
Wenn Sie jetzt Ihre erste GitLab CI CD Pipeline aufbauen wollen, starten Sie mit einem einfachen Test-Job. Fügen Sie nach und nach Build- und Deploy-Jobs hinzu. Innerhalb weniger Sprints haben Sie eine vollständige GitLab CI CD Pipeline die Ihrem Team täglich Zeit spart. TOSMedia begleitet Sie bei jedem Schritt – von der GitLab-Installation bis zur produktiven Multi-Stage-Pipeline mit automatischen Security-Scans und Zero-Downtime-Deployments.
Zögern Sie nicht zu lange mit der Einführung Ihrer ersten GitLab CI CD Pipeline. Jeder Tag ohne automatisierte Tests und Deployments ist ein verpasstes Potential für schnellere Releases und weniger manuelle Fehler. Die initiale Investition in eine gut konfigurierte GitLab CI CD Pipeline zahlt sich innerhalb weniger Sprints aus. Teams die CI/CD konsequent nutzen, deployen im Schnitt 46 Mal häufiger bei gleichzeitig niedrigerer Change-Failure-Rate – so das State-of-DevOps-Report 2023 von Google.
Unternehmen die eine GitLab CI CD Pipeline konsequent einsetzen, reduzieren die Mean Time to Recovery (MTTR) bei Produktionsproblemen dramatisch: automatische Rollbacks, klare Deployment-History und reproduzierbare Builds machen die Fehlersuche deutlich einfacher. Eine gute GitLab CI CD Pipeline ist damit nicht nur ein Produktivitäts-Tool, sondern auch ein Risikomanagement-Instrument.
→ GitLab CI/CD Beratung anfragen | Lösungen von TOSMedia | IT-Services | GitLab CI/CD Dokumentation | GitLab Runner Dokumentation

Christian Vetters


