📝 docs: update workflow README with new multi-workflow architecture

2026-04-09 09:19:58 +02:00
parent ebc131f33b
commit 1f8c5450d5
1 changed files with 154 additions and 48 deletions
--- a/.gitea/workflows/README.md
+++ b/.gitea/workflows/README.md
@@ -1,57 +1,163 @@
-# CI/CD Workflow Documentation
+# CI/CD Workflow Architecture

-## Workflow Structure
+## 🗺️ Overview

-The CI/CD pipeline consists of three jobs:
+The dance-lessons-coach project uses a **multi-workflow architecture** for better separation of concerns, maintainability, and flexibility.

-### 1. build-cache
- **Purpose**: Build and cache Docker build dependencies
- **Runs on**: `ubuntu-latest-ca`
- **Container**: None (runs directly on runner)
- **Outputs**: `deps_hash` and `cache_hit`
+## 📁 Workflow Files

-### 2. ci-pipeline
- **Purpose**: Run tests, build binaries, and update documentation
- **Runs on**: `ubuntu-latest-ca`
- **Container**: Uses cached build image from `build-cache` job
- **Services**: PostgreSQL for BDD tests
- **Steps**:
-  - Checkout code
-  - Set database environment variables
-  - Generate Swagger documentation
-  - Build all packages
-  - Run BDD tests with coverage
-  - Run unit tests with coverage
-  - Run code formatting
-  - Build binaries
-  - Update badges and version
+### 1. `ci-cd.yaml` - Main CI/CD Pipeline

-### 3. docker-push
- **Purpose**: Build and push Docker images to registry
- **Runs on**: `ubuntu-latest-ca`
- **Container**: None (runs directly on runner)
- **Trigger**: Only on `main` branch or `feature/move-docker-job` branch
- **Steps**:
-  - Checkout code
-  - Login to Gitea Container Registry
-  - Build production Docker image
-  - Push image with version, latest, and commit SHA tags
-  - Show published images
+**Purpose**: Run tests, build binaries, and generate documentation

-## Key Design Decisions
+**Triggers**:
+- Push to `main`, `ci/**`, `feature/**`, `fix/**`, `refactor/**` branches
+- Pull requests to `main` branch
+- Manual workflow dispatch

-### Separate Docker Push Job
-The Docker push steps were moved to a separate job because:
- The CI container doesn't have Docker commands available
- Docker operations require direct access to the host's Docker daemon
- This separation allows the CI job to run in a container while Docker operations run on the host
+**Jobs**:
+1. **build-cache** - Build and cache Docker build environment
+2. **ci-pipeline** - Run tests, build binaries, generate Swagger docs
+3. **trigger-docker-push** - Trigger separate Docker workflow on main branch

-### Job Dependencies
- `docker-push` depends on both `build-cache` and `ci-pipeline`
- This ensures Docker images are only built after all tests pass
- The dependency hash from `build-cache` is used for consistent Docker builds
+**Key Features**:
+- Runs in container environment with all build tools
+- Generates Swagger documentation
+- Runs BDD and unit tests with PostgreSQL
+- Updates badges and version information
+- Triggers Docker workflow only on main branch

-### Conditional Execution
- Docker push only runs on `main` branch (and temporarily on `feature/move-docker-job` for testing)
- All jobs skip if commit message contains `[skip ci]`
- All jobs skip if actor is `ci-bot` to prevent infinite loops
+### 2. `docker-push.yaml` - Docker Image Publishing
+
+**Purpose**: Build and push Docker images to registry
+
+**Triggers**:
+- Manual workflow dispatch only (no automatic triggers)
+- Triggered by `ci-cd.yaml` on main branch
+
+**Jobs**:
+1. **docker-push** - Build production Docker image and push to registry
+
+**Key Features**:
+- Runs on host environment (access to Docker daemon)
+- Uses dependency hash from build-cache
+- Builds minimal Alpine-based production image
+- Pushes multiple tags (version, latest, commit SHA)
+
+## 🔧 Architecture Benefits
+
+### 1. Clear Separation of Concerns
+- **CI/CD Pipeline**: Testing and artifact generation
+- **Docker Publishing**: Image building and registry operations
+
+### 2. Proper Environment Isolation
+- **CI jobs run in container**: Consistent build environment
+- **Docker jobs run on host**: Access to Docker daemon
+
+### 3. Flexible Testing
+- Can trigger Docker workflow independently for testing
+- No complex conditional logic in main workflow
+- Easier to debug and maintain
+
+### 4. Better Security
+- Docker operations isolated in separate workflow
+- Clear dependency between test success and deployment
+- Manual trigger capability for emergency situations
+
+## 🚀 Usage Examples
+
+### Trigger Full CI/CD Pipeline
+```bash
+# Automatically triggered on push to main branch
+# Or manually:
+./scripts/gitea-client.sh trigger-workflow arcodange dance-lessons-coach ci-cd.yaml main
+```
+
+### Trigger Docker Push Manually
+```bash
+# Get dependency hash from build-cache job first
+DEPS_HASH="abc123def456"
+
+# Trigger Docker workflow manually
+./scripts/gitea-client.sh trigger-workflow arcodange dance-lessons-coach docker-push.yaml main --deps_hash $DEPS_HASH
+```
+
+### Workflow Dispatch Parameters (docker-push.yaml)
+- `deps_hash` (required): Dependency hash from build-cache job
+- `ref` (optional): Git reference (branch/tag), defaults to current
+
+## 🔗 Workflow Dependencies
+
+```mermaid
+graph TD
+    A[Push to main] --> B[ci-cd.yaml]
+    B --> C[build-cache job]
+    B --> D[ci-pipeline job]
+    D --> E[trigger-docker-push job]
+    E --> F[docker-push.yaml]
+    F --> G[docker-push job]
+    G --> H[Docker Registry]
+```
+
+## 📋 Best Practices
+
+### 1. Always Run CI First
+- Docker workflow should only be triggered after CI passes
+- Maintains quality gate before deployment
+
+### 2. Use Dependency Hash
+- Ensures consistent builds across workflows
+- Pass hash from build-cache to docker-push
+
+### 3. Manual Testing
+- Use separate Docker workflow for testing image builds
+- Avoids polluting main branch with test images
+
+### 4. Monitor Both Workflows
+- CI/CD workflow for test results and artifacts
+- Docker workflow for image build and push status
+
+## 🎯 Future Enhancements
+
+### Potential Improvements:
+- Add workflow status badges to README
+- Implement workflow chaining with outputs
+- Add matrix builds for multiple architectures
+- Implement canary deployment workflow
+- Add rollback capability
+
+### Architecture Considerations:
+- Keep workflows focused on single responsibilities
+- Maintain clear separation between test and deploy
+- Document all workflow triggers and conditions
+- Monitor workflow execution times and optimize
+
+## 📝 Maintenance
+
+### Adding New Jobs:
+- Add to appropriate workflow based on responsibility
+- CI-related jobs → `ci-cd.yaml`
+- Docker-related jobs → `docker-push.yaml`
+
+### Modifying Triggers:
+- Update trigger conditions in respective workflow files
+- Test changes thoroughly before merging
+
+### Debugging:
+- Check workflow logs in Gitea Actions
+- Use `gitea-client.sh diagnose-job` for detailed analysis
+- Monitor workflow dependencies and execution order
+
+## 🔒 Security
+
+### Secrets Management:
+- Docker registry credentials stored in Gitea secrets
+- Never hardcode credentials in workflow files
+- Use GitHub token for workflow dispatch
+
+### Access Control:
+- Only authorized users can trigger workflows
+- Manual approval required for production deployments
+- Audit logs available for all workflow executions
+
+This architecture provides a clean, maintainable, and secure CI/CD pipeline that scales well with project growth while maintaining clear separation of concerns.