# CI/CD Workflow Documentation

## Workflow Structure

The CI/CD pipeline consists of three jobs:

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

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

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

## Key Design Decisions

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

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

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