# CI/CD Gitea starter

Empty on purpose: only CI/CD, Docker, compose, and instructions so you can drop your app in.

## Structure
- `.gitea/workflows/ci.yml`: lint -> test -> build with auto-versioning, git tags, Docker images `latest` + `vX.Y.Z`.
- `.gitea/workflows/deploy.yml`: manual Deploy (`workflow_dispatch`) to staging or prod.
- `docker-compose.staging.yml` / `docker-compose.prod.yml`: per-environment compose.
- `Dockerfile`: skeleton image to replace with your app build.
- `/opt/mon-projet/env/{staging,prod}/.env`: generated on the VPS from Gitea secrets.
- `.commitlintrc.yml`: commit linting rules (conventional-style) enforced in CI.
- `scripts/commit-msg.sh`: local commit-msg hook helper (commitlint via npx, no Docker).

## Required Gitea secrets
- `DOCKER_REGISTRY`: registry (e.g. registry.example.com).
- `DOCKER_IMAGE`: image name (e.g. mon-projet).
- `DOCKER_USERNAME` / `DOCKER_PASSWORD`: registry credentials.
- `GITEA_TOKEN`: token with push rights on the repo (for git tag push).
- `STAGING_ENV_VARS`: full `.env` content for staging (multi-line allowed).
- `PROD_ENV_VARS`: full `.env` content for prod.

## CI workflow (ci.yml)
- Triggers: `push` and `pull_request`.
- Strict order: `commitlint` -> `lint` -> `test` -> `build`. Any failure stops later jobs.
- Auto-versioning rules (conventional commits):
  - `feat:` => MINOR, `fix:` => PATCH, `feat!` or `BREAKING CHANGE` => MAJOR.
  - Tag created (`vX.Y.Z`) + changelog artifact on pushes to `main`.
- Builds and pushes Docker images `latest` and `vX.Y.Z` to the configured registry.

## Deploy workflow (deploy.yml)
- Trigger: manual only (`workflow_dispatch`) with input `env` (`staging` | `prod`) and optional `version` (to force a prod tag).
- Jobs: `prepare` -> `build` -> `deploy-*` (staging or prod). Deployments always depend on the build.
- Build: rebuilds and pushes both tags (`latest` + `vX.Y.Z`) before any deploy.
- `.env` generation: secrets `STAGING_ENV_VARS` / `PROD_ENV_VARS` are written on the VPS to `/opt/mon-projet/env/<env>/.env`.
- Docker deploy: `docker compose pull` then `docker compose up -d` with the dedicated compose files.
- Prod uses the explicit version tag; staging consumes `latest`.

## Local commitlint (optional)
- Requires Node.js + npm locally (no Docker).
- One-time setup: `npm install --save-dev @commitlint/cli`
- Install the hook: `cp scripts/commit-msg.sh .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg`
- The hook will block commits whose messages are not conventional-style (`feat`, `fix`, `chore`, etc.).
- Windows (Git Bash) : chmod est optionnel ; copie simplement le fichier dans `.git/hooks/commit-msg`. Vérifie que `npx` fonctionne (`npx --version`).

## Pour un débutant : comment ça marche ?
- Commits propres : écris tes messages comme `feat: ...` (nouvelle fonctionnalité) ou `fix: ...` (correction). Ça pilote l’auto-versioning.
- Pousser le code : un `git push` ou une PR lance la CI (vérifie les commits, le lint, les tests, construit l’image Docker).
- Versions automatiques : sur la branche `main`, la CI calcule la prochaine version `vX.Y.Z`, tague le repo et pousse les images Docker (`latest` et `vX.Y.Z`).
- Déploiements : rien d’automatique. Tu lances manuellement le workflow **Deploy** dans l’onglet Actions de Gitea :
  - Choisis `staging` pour déployer l’image `latest`.
  - Choisis `prod` pour déployer l’image `vX.Y.Z` (dernier tag ou celui que tu fournis dans l’input `version`).
- Secrets : tes mots de passe/variables sensibles restent dans l’UI Gitea (pas dans le code). Ils servent à créer les fichiers `.env` sur le serveur et à pousser les images.
- Serveur : le runner doit avoir Docker/compose et pouvoir écrire dans `/opt/mon-projet/`. Les `.env` sont générés à chaque déploiement et ne sont jamais commités.

## How to use
1) Update `Dockerfile`, lint/test commands in `ci.yml`, and services/ports/volumes in compose files to match your app.
2) Add the secrets above in the Gitea repo settings.
3) Push code with commit messages `feat:`, `fix:`, or `feat!`/`BREAKING CHANGE` to drive semver bumps.
4) Make sure CI is green. No automatic deployment will run if CI fails (and deploy stays manual).
5) Run the **Deploy** workflow in Gitea Actions:
   - `env=staging`: deploys image `latest`.
   - `env=prod`: deploys image tagged `vX.Y.Z` (latest tag by default or the one supplied via `version`).

## Notes
- Runner must access `/opt/mon-projet/` and Docker/compose.
- `.env` files are never versioned; they are regenerated on each deploy from secrets.
- If no tag exists yet, provide `version` manually for a prod deploy.