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](./code-deployment-workflow.md) - Unterschiede zwischen Rsync und Git
- [Initial Deployment Guide](./initial-deployment-guide.md) - Initial Deployment Anleitung
- [Application Stack Deployment](../reference/application-stack.md) - Detaillierter Ablauf
- [CI/CD Status](../status/ci-cd-status.md) - 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

```bash
# 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

```bash
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

```bash
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

```bash
# 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:**
```bash
# 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-workflow.md) - Code-Deployment-Methoden
- [Initial Deployment Guide](./initial-deployment-guide.md) - Initial Deployment
- [Application Stack Deployment](../reference/application-stack.md) - Detaillierter Ablauf
- [CI/CD Status](../status/ci-cd-status.md) - Aktueller Status
- [Troubleshooting Guide](../troubleshooting/initial-deployment-issues.md) - Probleme und Lösungen