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) :

```bash
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) :

```bash
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`) :

```bash
# 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).