arcodange/dance-lessons-coach
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Gabriel Radureau
2026-04-09 09:19:58 +02:00
parent ebc131f33b
commit 1f8c5450d5
1 changed files with 154 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
.gitea/workflows/README.md
View File

@@ -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 ## 📁 Workflow Files
- **Purpose**: Build and cache Docker build dependencies
- **Runs on**: `ubuntu-latest-ca`
- **Container**: None (runs directly on runner)
- **Outputs**: `deps_hash` and `cache_hit`
### 2. ci-pipeline ### 1. `ci-cd.yaml` - Main CI/CD 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
### 3. docker-push **Purpose**: Run tests, build binaries, and generate documentation
- **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
## Key Design Decisions **Triggers**:
- Push to `main`, `ci/**`, `feature/**`, `fix/**`, `refactor/**` branches
- Pull requests to `main` branch
- Manual workflow dispatch
### Separate Docker Push Job **Jobs**:
The Docker push steps were moved to a separate job because: 1. **build-cache** - Build and cache Docker build environment
- The CI container doesn't have Docker commands available 2. **ci-pipeline** - Run tests, build binaries, generate Swagger docs
- Docker operations require direct access to the host's Docker daemon 3. **trigger-docker-push** - Trigger separate Docker workflow on main branch
- This separation allows the CI job to run in a container while Docker operations run on the host
### Job Dependencies **Key Features**:
- `docker-push` depends on both `build-cache` and `ci-pipeline` - Runs in container environment with all build tools
- This ensures Docker images are only built after all tests pass - Generates Swagger documentation
- The dependency hash from `build-cache` is used for consistent Docker builds - Runs BDD and unit tests with PostgreSQL
- Updates badges and version information
- Triggers Docker workflow only on main branch
### Conditional Execution ### 2. `docker-push.yaml` - Docker Image Publishing
- 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]` **Purpose**: Build and push Docker images to registry
- All jobs skip if actor is `ci-bot` to prevent infinite loops
**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.