Funk-lab/admin/k8s/forgejo.md

Forgejo — Git self-host (miroir de GitHub)

Forge Git Forgejo dans le cluster, exposée dans le hub (git.funklab.online, SSO Authentik) et configurée en miroir lecture seule du dépôt GitHub Funk-lab. GitHub reste la source de vérité (ArgoCD continue d'y tirer, rien n'est modifié) ; Forgejo en fournit une copie locale synchronisée + une UI + de la résilience.

Namespace : ai. Base PostgreSQL sur storage-01 (pattern Ghostfolio/n8n).

Vue d'ensemble

GitHub (Funk-lab, source de vérité)
   │  pull-mirror (toutes les ~10 min, HTTPS + PAT lecture)
   ▼
Forgejo (cluster, ns ai) ──HTTPS──▶ git.funklab.online (SSO Authentik) / git.lab.local (LAN)
   │
   └─ dépôts sur PVC nfs `forgejo-data` ; métadonnées sur PostgreSQL s01 (base `forgejo`)

• Sens de synchro : GitHub → Forgejo uniquement (miroir). On ne pousse pas depuis Forgejo. ArgoCD n'est pas touché (il tire toujours git@github.com:...Funk-lab).
• Clone HTTPS uniquement (DISABLE_SSH=true) — pas de port 22 supplémentaire exposé.

Composants

• Deployment forgejo (k8s/apps/forgejo/) : image codeberg.org/forgejo/forgejo:11, config par variables d'env FORGEJO__section__CLE (pas d'app.ini versionné).
• PVC forgejo-data (RWO, nfs, 10Gi) monté sur /data : dépôts git + app.ini généré (dont INTERNAL_TOKEN persistant).
• PostgreSQL sur storage-01 : base + user forgejo (rôle Ansible postgresql).
• IngressRoutes : git.lab.local (interne, web) + git.funklab.online (websecure, Let's Encrypt, + middlewares security-headers/ratelimit).

Secrets

Vault Ansible (make vault-view) :

Variable	Usage
vault_pg_forgejo_password	Base PG forgejo (= clé pg-password du secret k8s)
vault_forgejo_oauth_client_secret	Client secret OIDC Forgejo côté Authentik
vault_forgejo_admin_password	Mot de passe de l'admin local break-glass forgejo-admin

Secret k8s (créé à la main, hors git, comme les autres apps) :

kubectl -n ai create secret generic forgejo-secret \
  --from-literal=pg-password='<vault_pg_forgejo_password>' \
  --from-literal=secret-key="$(openssl rand -base64 32)"

secret-key chiffre les données sensibles internes de Forgejo — le fixer via le secret (plutôt que le laisser régénérer) garde les sessions stables entre redéploiements.

Déploiement (ordre)

1. Base : ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags postgresql (crée la base + user forgejo).
2. Secret k8s ci-dessus (avant le 1er sync, sinon CreateContainerConfigError).
3. Merge sur main → ArgoCD crée l'Application forgejo (~3 min).
4. OIDC + admin + miroir : étapes ci-dessous (config en base, hors IaC).

Configuration OIDC (Authentik + Forgejo)

Côté Authentik (UI)

1. Providers → Create → OAuth2/OpenID Provider :
   • Name forgejo, flow implicit-consent, Client type : Confidential
   • Client ID forgejo · Client Secret = vault_forgejo_oauth_client_secret
   • Redirect URI (Strict) : https://git.funklab.online/user/oauth2/authentik/callback
   • Signing Key : le certificat self-signed
2. Applications → Create : Name Forgejo, slug forgejo, provider forgejo, Launch URL https://git.funklab.online
3. Bindings → lier un groupe (ou ouvert). Membres de lab-admins → admin Forgejo.

Côté Forgejo (CLI, une fois)

La source d'auth OIDC s'ajoute par commande (config en base — pas d'admin préalable requis) :

kubectl -n ai exec deploy/forgejo -- forgejo admin auth add-oauth \
  --name authentik \
  --provider openidConnect \
  --key forgejo \
  --secret '<vault_forgejo_oauth_client_secret>' \
  --auto-discover-url https://auth.funklab.online/application/o/forgejo/.well-known/openid-configuration \
  --group-claim-name groups \
  --admin-group lab-admins \
  --scopes openid --scopes profile --scopes email

Ensuite : https://git.funklab.online → bouton « Se connecter avec authentik ». Le premier utilisateur créé devient admin ; via --admin-group lab-admins, tout membre du groupe est admin.

⚠️ DISABLE_REGISTRATION doit rester false (avec ALLOW_ONLY_EXTERNAL_REGISTRATION=true) : à true il bloque aussi l'auto-provisioning OIDC → écran « inscriptions désactivées » après un login pourtant réussi.

Admin local break-glass

Accès de secours si Authentik est HS (Forgejo n'a aucun admin par défaut). Compte forgejo-admin déjà créé, mot de passe dans le vault (vault_forgejo_admin_password) :

# login local : https://git.funklab.online/user/login (formulaire en bas)
# (re)créer / réinitialiser si besoin :
kubectl -n ai exec deploy/forgejo -- su-exec git forgejo admin user create \
  --username forgejo-admin --email forgejo-admin@funklab.online \
  --password '<vault_forgejo_admin_password>' --admin --must-change-password=false

Le CLI forgejo refuse de tourner en root → toujours le préfixer de su-exec git.

Créer le miroir de Funk-lab

Une fois connecté (admin) : + → New Migration → GitHub :

• Clone Address : https://github.com/Alkatrazz24/Funk-lab.git
• Cocher « This repository will be a mirror »
• Le dépôt étant privé, renseigner un PAT GitHub en lecture seule (Settings GitHub → Developer settings → Fine-grained token, scope Contents: read sur Funk-lab)
• Owner : ton compte · Intervalle de synchro : 10m (défaut modifiable)

Forgejo re-tire alors GitHub automatiquement. Forcer une synchro : page du dépôt → Settings → Mirror Settings → Synchronize Now.

Alternative API (au lieu de l'UI) : POST /api/v1/repos/migrate avec "mirror": true et "auth_token": "<PAT>" (jeton Forgejo perso en en-tête).

Pièges / notes

1. Miroir = lecture seule : ne pas committer dans Forgejo, les changements seraient écrasés au prochain pull. Le workflow reste GitHub (PR) → ArgoCD.
2. Repo privé → PAT GitHub obligatoire à la création du miroir (sinon authentication required). Le PAT est stocké chiffré par Forgejo en base.
3. Config en base (source OIDC, miroir) hors IaC — comme Authentik/Guacamole. Backup PG = gap connu.
4. git.funklab.online déjà résolu par le wildcard OVH + dnsmasq split-horizon — aucun ajout DNS. Le cert Let's Encrypt s'émet au 1er accès (HTTP-01).
5. PVC RWO + strategy: Recreate : un seul pod monte /data. Ne pas passer en plusieurs réplicas sans stockage RWX + config HA.
6. Dépannage OIDC : kubectl -n ai logs deploy/forgejo | grep -i oauth. Redirect URI au caractère près et slug Authentik = forgejo (sinon discovery 404, cf. auth-portal).