163 lines
5.0 KiB
Markdown
163 lines
5.0 KiB
Markdown
# CI/CD Workflow Architecture
|
|
|
|
## 🗺️ Overview
|
|
|
|
The dance-lessons-coach project uses a **multi-workflow architecture** for better separation of concerns, maintainability, and flexibility.
|
|
|
|
## 📁 Workflow Files
|
|
|
|
### 1. `ci-cd.yaml` - Main CI/CD Pipeline
|
|
|
|
**Purpose**: Run tests, build binaries, and generate documentation
|
|
|
|
**Triggers**:
|
|
- Push to `main`, `ci/**`, `feature/**`, `fix/**`, `refactor/**` branches
|
|
- Pull requests to `main` branch
|
|
- Manual workflow dispatch
|
|
|
|
**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
|
|
|
|
**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
|
|
|
|
### 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. |