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.