factory/doc/runbooks/new-web-app/01-gitea-repo.md

Factory > Doc > Runbooks > Nouvelle application web > 1. Dépôt Gitea

1. Créer le dépôt Gitea

Status: ✅ Active Downstream: 2. Base de données, 3. Vault plateforme Related: Conventions de nommage · 6. Workflows CI

---

Summary

Tout part d'un dépôt Gitea nommé exactement <app> (voir conventions). Le créer sous l'organisation arcodange-org n'est pas un détail : c'est ce qui lui fait hériter automatiquement des secrets Actions d'organisation dont tous les workflows dépendent. Le dépôt contient un squelette fixe que les étapes suivantes viennent remplir.

Pourquoi sous arcodange-org

Les workflows .gitea/workflows/* (voir étape 6) référencent des secrets qui ne sont pas définis dans le dépôt mais au niveau de l'organisation et hérités par tous ses dépôts :

Secret d'organisation	Usage
HOMELAB_CA_CERT	CA interne (base64) pour parler en TLS à vault.arcodange.lab
vault_oauth__sh_b64	Script (base64) qui réalise l'échange OIDC Gitea → JWT Vault
PACKAGES_TOKEN	Token de push vers le registre d'images gitea.arcodange.lab

Ces secrets sont propagés par le rôle Ansible gitea_secret (gitea_owner_type: organization).

Important

Un dépôt créé hors arcodange-org (par ex. sous l'org arcodange) n'hérite pas forcément de ces secrets. Si tu surcharges l'org (cf. org: à l'étape 7), assure-toi que les mêmes secrets y existent.

Options pour créer le dépôt

Méthode	Quand	Comment
UI Gitea	one-shot manuel	https://gitea.arcodange.lab → New Repository sous arcodange-org
MCP Gitea	depuis un agent	outil mcp__gitea__create_repo (cf. règle « Gitea = MCP, pas gh » du guide global)
Rôle Ansible gitea_repo	reproductible/inventaire	roles/gitea_repo
Ressource Terraform gitea_repository	tout-en-IaC	dans factory/iac (provider go-gitea/gitea déjà configuré)

Squelette minimal du dépôt

<app>/
├── chart/                 # chart Helm — ArgoCD déploie CE dossier (path: chart)   → étape 4
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
├── iac/                   # Terraform/OpenTofu de l'app                            → étape 5
│   ├── providers.tf
│   ├── backend.tf
│   └── main.tf
├── .gitea/workflows/      # CI (tofu apply + build image)                          → étape 6
│   ├── vault.yaml
│   └── dockerimage.yaml   # uniquement si l'app build sa propre image
├── Dockerfile             # uniquement si l'app build sa propre image
├── README.md
└── .gitignore

Important

Le dossier du chart doit s'appeler chart/ et être à la racine : le template ArgoCD impose path: chart (cf. étape 7). Pas de helm/, pas de sous-dossier.

.gitignore recommandé

Aligné sur les dépôts existants (exclut tout secret local) :

.terraform
.terraform.*
.env
*.key
secrets/
.DS_Store

Le bot tofu_module_reader

La CI de l'app clone le module Terraform partagé tools en SSH (cf. étape 5). C'est l'utilisateur restreint tofu_module_reader (créé dans factory/iac/gitea_tofu_ci_user.tf, clé privée dans Vault kvv1/gitea/tofu_module_reader) qui sert d'identité de lecture. Rien à faire de spécial, mais le dépôt tools doit rester lisible par ce bot.

Notes / contraintes

• Le nom du dépôt = <app> exactement (kebab-case minuscule). Voir conventions — ce nom se propage partout.
• Pas besoin de protéger main autrement que par la convention worktree/PR de l'équipe ; ArgoCD suit HEAD.

Related

• 2. Base de données — provisionner la base, en parallèle de l'étape 3.
• 3. Vault plateforme — déclarer l'app côté Vault, en parallèle de l'étape 2.
• 6. Workflows CI — consomme les secrets d'org hérités ici.