dance-lessons-coach/.gitea/workflows/README.md

# 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.