📝 docs: add CI/CD workflow documentation

.gitea/workflows/README.md

@@ -0,0 +1,57 @@
+# 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