Forgejo
Audience
PLANA staff working on git, CI, or the container registry.
PLANA hosts its source code on Forgejo — the open-source fork of Gitea. Self-hosted at git.planapulse.com. Forgejo is also the container registry and the CI runner platform.
Why Forgejo
| Capability | Forgejo |
|---|---|
| Git host | ✓ |
| OCI registry (container images + Helm charts) | ✓ |
| CI runner (Forgejo Actions, mostly GitHub Actions-compatible) | ✓ |
| Issue / PR tracking | ✓ |
| OIDC client (signs in via Authentik) | ✓ |
| FOSS | ✓ (MIT-licensed; community-governed) |
One product, one operator surface, one auth domain. No GitHub / GitLab / Docker Hub / Bitbucket sprawl.
Deployment
| Component | Where |
|---|---|
| Forgejo server | forgejo namespace |
| Forgejo runners | forgejo-runner namespace |
| Database | forgejo on pg01 |
| Filesystem | block-storage PVC (retain reclaim policy) |
| Domain | git.planapulse.com |
Helm-based deployment, reconciled by Flux from infra/k8s/forgejo/.
URLs
| URL | Purpose |
|---|---|
https://git.planapulse.com | Web UI |
git@git.planapulse.com:plana-pulse/<repo>.git | SSH clone |
https://git.planapulse.com/<org>/<repo> | Browse |
https://git.planapulse.com/<org>/<repo>/raw/branch/main/<path> | Raw file |
https://git.planapulse.com/<org>/<repo>/archive/<sha>.tar.gz | Archive (used by CI) |
Two orgs
| Org | Use |
|---|---|
plana-pulse | The 32 PLANA Pulse repos (infra, pulse-*, odoo-modules, etc.) |
plana-docs | Documentation portal repo |
(vantage — separate Forgejo org for the Vantage project) |
Org-scoped CI runners ensure jobs don't mix across project boundaries.
Authentication
| Method | Use |
|---|---|
| OIDC via Authentik | Web sign-in for staff |
| SSH keys | Git push/pull |
| API tokens | For automation / CI |
Staff sign in once via Authentik; SSH keys are uploaded per-user to the Forgejo profile.
The oca-sync-bot-write SSH deploy key handles automated OCA module sync — it's per-repo, write-only, least-privilege.
Container registry
Forgejo's built-in OCI registry at git.planapulse.com:
git.planapulse.com/<org>/<image-name>:<tag>Examples:
git.planapulse.com/plana-pulse/pulse-account-api:abc1234
git.planapulse.com/plana-pulse/odoo-modules/base-18:abc1234
git.planapulse.com/plana-docs/portal:abc1234CI pushes; cluster pods pull. Per-namespace pull secrets (forgejo-registry) make this work.
CI runners
Forgejo Actions, broadly GitHub Actions-compatible:
| Runner | Org scope |
|---|---|
act-runner-main | Main plana-pulse org |
act-runner-vantage | Vantage org |
Both DaemonSets in forgejo-runner namespace. They poll Forgejo for queued jobs, execute, return results.
See Operations → CI/CD for pipeline patterns.
Backups
Standard pattern:
- Daily
pg_dumpof theforgejoDB to SOS (plana-pulse-backups) - Daily tar of the Forgejo data PVC to SOS
A Forgejo restore involves restoring both. Procedure in infra/docs/runbooks/forgejo-restore.md.
Updating Forgejo
Major version updates are rare (every 6-12 months). Procedure:
- Verify backup is recent
- Pull a Forgejo version with documented upgrade path
- Update the Helm values
- Roll out
- Soak for 24h
Forgejo's upgrade compatibility is excellent — most upgrades are seamless.
Where to read more
- Operations → CI/CD — using Forgejo Actions
- Identity → Authentik SSO — staff sign-in
- Secrets management — Forgejo credentials in SOPS
- Source:
infra/k8s/forgejo/