michaelschiemer/deployment/docs/guides/cicd-workflow-guide.md

CI/CD Workflow Guide

Stand: 2025-11-07
Status: Vollständige Dokumentation der CI/CD Workflows

---

Übersicht

Dieses Dokument erklärt die CI/CD Workflows und wie sie funktionieren. Die Workflows verwenden Ansible Playbooks für Deployment, um Idempotenz, bessere Fehlerbehandlung und konsistente Logs zu gewährleisten.

📖 Verwandte Dokumentation:

• Code Deployment Workflow - Unterschiede zwischen Rsync und Git
• Initial Deployment Guide - Initial Deployment Anleitung
• Application Stack Deployment - Detaillierter Ablauf
• CI/CD Status - Aktueller Status

---

Workflow-Übersicht

Automatische Workflows

.gitea/workflows/build-image.yml

• Trigger: Push zu staging oder main Branch
• Jobs:
  1. changes - Prüft ob Build notwendig ist
  2. test - Führt Tests aus (PHP, Pest, PHPStan, Code Style)
  3. build - Baut Docker Image und pusht zur Registry
  4. deploy-staging - Auto-Deploy zu Staging (nur bei staging Branch)
  5. deploy-production - Auto-Deploy zu Production (nur bei main Branch)

Manuelle Workflows

.gitea/workflows/manual-deploy.yml

• Trigger: Manuell via workflow_dispatch
• Inputs:
  • environment: staging oder production
  • image_tag: Optional, Image Tag zum Deployen
  • branch: Optional, Branch zum Checkout
• Jobs:
  1. determine-image - Bestimmt Image zum Deployen
  2. deploy-staging - Deploy zu Staging
  3. deploy-production - Deploy zu Production

---

Deployment-Prozess

Staging Auto-Deploy (build-image.yml)

Trigger: Push zu staging Branch

Ablauf:

1. Code-Deployment (deploy-application-code.yml)

   • Git Repository wird auf Server aktualisiert
   • Branch: staging
   • Ziel: /home/deploy/michaelschiemer/current

2. Composer Dependencies (install-composer-dependencies.yml)

   • composer install --no-dev --optimize-autoloader
   • Im php Container ausgeführt
   • queue-worker und scheduler werden neu gestartet

3. Image-Deployment (deploy-image.yml)

   • Docker Image wird zur Registry gepusht
   • Image wird auf Server gepullt
   • docker-compose.production.yml wird aktualisiert
   • Container werden neu gestartet

4. Health-Check

   • Prüft https://staging.michaelschiemer.de/health
   • Wartet bis zu 10 Versuche (100 Sekunden)

Production Auto-Deploy (build-image.yml)

Trigger: Push zu main Branch

Ablauf:

1. Code-Deployment (deploy-application-code.yml)

   • Git Repository wird auf Server aktualisiert
   • Branch: main
   • Ziel: /home/deploy/michaelschiemer/current

2. Composer Dependencies (install-composer-dependencies.yml)

   • Gleicher Prozess wie Staging

3. Image-Deployment (deploy-image.yml)

   • Gleicher Prozess wie Staging
   • Environment: production

4. Health-Check

   • Prüft https://michaelschiemer.de/health
   • Wartet bis zu 10 Versuche (100 Sekunden)

---

Ansible Playbooks in Workflows

deploy-application-code.yml

Zweck: Code-Deployment via Git

Parameter:

• deployment_environment: staging oder production
• deployment_hosts: production (Inventory Group)
• git_branch: Branch zum Deployen (staging oder main)

Was passiert:

• Git Repository wird geklont (falls nicht vorhanden)
• Repository wird aktualisiert (git pull)
• Executable Permissions werden gesetzt
• Verifikation: Prüft ob worker.php, console.php, composer.json existieren

install-composer-dependencies.yml

Zweck: Composer Dependencies Installation

Parameter:

• deployment_environment: staging oder production

Was passiert:

• composer install --no-dev --optimize-autoloader im PHP Container
• Verifikation: Prüft ob vendor/autoload.php existiert
• Restart: queue-worker und scheduler (nur Production)

deploy-image.yml

Zweck: Docker Image Deployment

Parameter:

• deployment_environment: staging oder production
• image_tag: Image Tag (z.B. latest, git-abc1234)
• docker_registry: Registry URL
• docker_registry_username: Registry Username
• docker_registry_password: Registry Password

Was passiert:

• Docker Registry Login
• Image Pull
• docker-compose.production.yml wird aktualisiert
• Container werden neu gestartet
• Container Status wird angezeigt

---

Secrets Konfiguration

Erforderliche Secrets

REGISTRY_USER

• Docker Registry Benutzername
• Standard: admin

REGISTRY_PASSWORD

• Docker Registry Passwort
• Zu finden in: deployment/stacks/registry/auth/htpasswd

SSH_PRIVATE_KEY

• SSH Private Key für Production-Server-Zugriff
• Kompletter Inhalt inkl. -----BEGIN OPENSSH PRIVATE KEY-----

ANSIBLE_VAULT_PASSWORD

• Ansible Vault Password für verschlüsselte Secrets
• Optional: Falls nicht gesetzt, wird leeres Password File verwendet

GITEA_TOKEN (optional)

• Gitea Personal Access Token
• Für automatische Issue-Erstellung bei Security-Scans

Secrets konfigurieren

# In Gitea UI:
https://git.michaelschiemer.de/michael/michaelschiemer/settings/secrets/actions

# Secrets hinzufügen:
- REGISTRY_USER
- REGISTRY_PASSWORD
- SSH_PRIVATE_KEY
- ANSIBLE_VAULT_PASSWORD

---

Workflow-Beispiele

Staging Deployment (Automatisch)

Trigger: Push zu staging Branch

git checkout staging
git add .
git commit -m "feat: Add new feature"
git push origin staging

Was passiert automatisch:

1. Tests werden ausgeführt
2. Docker Image wird gebaut
3. Image wird zur Registry gepusht
4. Code wird via Git deployt
5. Composer Dependencies werden installiert
6. Image wird deployt
7. Health-Check wird durchgeführt

Production Deployment (Automatisch)

Trigger: Push zu main Branch

git checkout main
git merge staging
git push origin main

Was passiert automatisch:

• Gleicher Prozess wie Staging, aber auf Production

Manuelles Deployment

Via Gitea UI:

1. Gehe zu: https://git.michaelschiemer.de/michael/michaelschiemer/actions
2. Wähle: "Manual Deployment"
3. Klicke: "Run workflow"
4. Wähle:
   • Environment: production oder staging
   • Image Tag: Optional (z.B. git-abc1234)
   • Branch: Optional (Standard: main für Production, staging für Staging)

---

Troubleshooting

Problem: Code-Deployment schlägt fehl

Ursachen:

• Git Repository existiert nicht auf Server
• Git Credentials fehlen
• Branch existiert nicht

Lösung:

• Prüfe deploy-application-code.yml Logs
• Prüfe ob Git Repository auf Server existiert
• Prüfe Branch-Name

Problem: Composer Dependencies Installation schlägt fehl

Ursachen:

• composer.json fehlt
• PHP Container läuft nicht
• Netzwerk-Probleme

Lösung:

• Prüfe ob composer.json existiert
• Prüfe PHP Container Status
• Prüfe install-composer-dependencies.yml Logs

Problem: Image-Deployment schlägt fehl

Ursachen:

• Registry Login fehlgeschlagen
• Image existiert nicht in Registry
• Docker Compose Dateien fehlen

Lösung:

• Prüfe Registry Credentials
• Prüfe ob Image in Registry existiert
• Prüfe deploy-image.yml Logs

Problem: Health-Check schlägt fehl

Ursachen:

• Container starten nicht
• Application hat Fehler
• Health-Check Endpoint nicht erreichbar

Lösung:

• Prüfe Container Status: docker compose ps
• Prüfe Container Logs: docker compose logs
• Prüfe Health-Check Endpoint manuell: curl https://michaelschiemer.de/health

---

Best Practices

1. Staging First

Empfohlen: Immer zuerst auf Staging deployen, dann auf Production

# 1. Staging
git push origin staging  # → Auto-Deploy zu Staging

# 2. Testen auf Staging
# ... Tests durchführen ...

# 3. Production
git checkout main
git merge staging
git push origin main  # → Auto-Deploy zu Production

2. Image Tags

Empfohlen: Spezifische Image Tags verwenden statt latest

Vorteile:

• Rollback möglich
• Nachvollziehbarkeit
• Reproduzierbarkeit

Beispiel:

# Manuelles Deployment mit spezifischem Tag
# Image Tag: git-abc1234

3. Vault Password

Empfohlen: ANSIBLE_VAULT_PASSWORD als Secret konfigurieren

Vorteile:

• Automatisiertes Deployment
• Keine manuelle Eingabe nötig
• Sicherer als manuelle Eingabe

4. Monitoring

Empfohlen: Pipeline-Status überwachen

Methoden:

• Gitea Actions UI
• Health-Check Endpoints
• Container Status

---

Referenz

• Code Deployment Workflow - Code-Deployment-Methoden
• Initial Deployment Guide - Initial Deployment
• Application Stack Deployment - Detaillierter Ablauf
• CI/CD Status - Aktueller Status
• Troubleshooting Guide - Probleme und Lösungen