From 7805b3d2ade861515243e337b48cef32dc6393eb Mon Sep 17 00:00:00 2001
From: Gabriel Radureau <arcodange@gmail.com>
Date: Thu, 9 Apr 2026 08:39:34 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20CI/CD=20workflow?=
 =?UTF-8?q?=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitea/workflows/README.md | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 .gitea/workflows/README.md

diff --git a/.gitea/workflows/README.md b/.gitea/workflows/README.md
new file mode 100644
index 0000000..2cea66e
--- /dev/null
+++ b/.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