10d8647b50
Some checks failed
CI / commitlint (pull_request) Has been cancelled
CI / lint (pull_request) Has been cancelled
CI / test (pull_request) Has been cancelled
CI / build (pull_request) Has been cancelled
CI / commitlint (push) Has been cancelled
CI / lint (push) Has been cancelled
CI / test (push) Has been cancelled
CI / build (push) Has been cancelled
68 lines
4.5 KiB
Markdown
68 lines
4.5 KiB
Markdown
# 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.
|