forgejo

Metadata

Field	Value
Service	forgejo
Purpose	Self-hosted Git forge and collaboration platform
Criticality	Tier 2
Owner	Platform / SCM owner
Clusters	local, ozilab
Namespace	forgejo
Exposure	internet
Stateful	yes
Backup class	snapshot
RPO / RTO	Daily backup target, 2 to 6 hours to restore
Last reviewed	2026-09-02

1. Service Overview

Forgejo provides source-control, issue tracking, and collaboration features for self-hosted repositories. Two instances run from the same base: git.mutana.fr on the local cluster ("Arnaud's forge", also hosting this repository's CI) and git.lab.mutana.fr on the ozilab cluster ("Ozilab's forge").

Summary

If a Forgejo instance fails, operators lose access to Git hosting and collaboration workflows backed by that instance. The local instance additionally breaks repository CI (Forgejo Actions validation) when unavailable.

Dependencies

Dependency	Type	Why it matters
PostgreSQL	database	Stores Forgejo application state
Traefik	ingress	External HTTPS and Git access path
SMTP (mail.mutana.fr)	mailer	Notification and registration-confirmation email
Authelia	access control	Optional protection for the public route

2. Architecture Diagram

[Browser / git client]
  -> [Traefik]
  -> [Forgejo]
  -> [PostgreSQL]
  -> [PVC-backed application data]

3. Deployment Specifications

Item	Value
Source path	forgejo/base and forgejo/overlays/
Deployment model	Kustomize; single entry point shared by kubectl and Fleet
Namespace	forgejo
Workload kind	Deployment plus PostgreSQL StatefulSet
Image versions	forgejo 16.0.3 , postgres 18 — pinned in each overlay
Config files	base/forgejo-config.yaml (shared keys), overlays//kustomization.yaml, overlays//forgejo-config.env (cluster-specific keys), fleet.yaml

Fleet and kubectl apply -k build the same overlay directory (same principle as prometheus/); there is no separate Fleet copy of any config file.

Cluster mapping

Cluster	Overlay path	Fleet	Hostname	TLS
local	forgejo/overlays/local	onboarding — local GitRepo (fleet-local)	git.mutana.fr	default (tls: {})
ozilab	forgejo/overlays/ozilab	yes — ozilab GitRepo	git.lab.mutana.fr	certResolver: LE-prod

4. Configuration Guide

Environment variables

Variable	Source	Purpose	Secret?
Forgejo runtime settings (FORGEJO__*)	ConfigMap forgejo-config (shared base ConfigMap merged with the overlay's committed forgejo-config.env)	App name, domain, mailer host, actions, metrics, cron	no
FORGEJO__MAILER__PASSWD	Secret forgejo-secrets	SMTP authentication	yes
FORGEJO__DATABASE__PASSWD	Secret forgejo-secrets (key POSTGRES_PASSWORD)	Database authentication	yes
POSTGRES_*	Secret forgejo-secrets	Database bootstrap	yes

Secrets management

• Secret names: forgejo-secrets (namespace forgejo) — one Secret carrying the mailer key and the POSTGRES_* bootstrap keys.
• Source of truth: out-of-band env file per overlay (.forgejo-secrets.env, gitignored; the single .example placeholder is committed at the forgejo workload root). Created/updated by forgejo/bootstrap-secrets.sh overlays/<cluster>. Not generated by Kustomize or Fleet.
• Rotation trigger: mail credential change, database rotation, or security response. Re-run the bootstrap script, then restart the pods.
• What breaks if missing: pods fail with CreateContainerConfigError (missing env source); database pod cannot start.

5. Access Protocols

Path	URL or endpoint	Audience	Auth	TLS terminates at
External (local)	https://git.mutana.fr	Developers and operators	Forgejo auth and optional Authelia	Traefik
External (ozilab)	https://git.lab.mutana.fr	Developers and operators	Forgejo auth and optional Authelia	Traefik (LE-prod)
Internal	Services inside the forgejo namespace	Cluster workloads	namespace RBAC	Traefik / Forgejo

ozilab access control (2026-09-22)

overlays/ozilab/forgejo-config.env was corrected and hardened. Five keys had no section segment, so environment-to-ini never applied them; they are now section-qualified and therefore active for the first time. The instance is single-tenant:

Setting	Value	Effect
service.DISABLE_REGISTRATION	true	No self-signup
service.REQUIRE_SIGNIN_VIEW	true	No anonymous read (newly effective)
service.SHOW_REGISTRATION_BUTTON	false	No signup UI
openid.ENABLE_OPENID_SIGNIN / SIGNUP	false	No third-party identity
admin.DISABLE_REGULAR_ORG_CREATION	true	Only the admin creates orgs
repository.FORCE_PRIVATE	true	Repos cannot be made public
repository.signing.DEFAULT_TRUST_MODEL	committer	A signature counts only when it matches the committer
server.DOMAIN	git.lab.mutana.fr	Now matches ROOT_URL
api.ENABLE_SWAGGER, federation.ENABLED	false	Surface reduction

Because registration is disabled and SECURITY__INSTALL_LOCK=true, the initial admin must be created out of band with overlays/ozilab/bootstrap-admin.sh, which reads a gitignored .forgejo-admin.env. Further accounts are created from Site Administration → User Accounts.

Newly effective as a side effect: service.ENABLE_NOTIFY_MAIL, so the instance begins sending notification mail through mail.mutana.fr. See forgejo/README.md for the rollout and rollback notes.

6. Operations and Observability

• Primary health indicators: Forgejo Deployment available (/api/healthz startup/readiness probes), PostgreSQL StatefulSet ready (pg_isready probes), and web/UI plus Git access responsive.
• Dashboards or alerts: shared cluster monitoring and ingress health. Forgejo's own /metrics endpoint is enabled via config.
• Log locations: forgejo app pod logs and PostgreSQL logs.
• Known failure modes: DB connectivity loss, PVC issues, ingress misrouting, missing out-of-band Secrets.

7. Backup and Recovery Notes

• Backup method: PostgreSQL backup plus PVC snapshot (volumes are local-path on local, longhorn on ozilab).
• Restore prerequisites: database dump or persistent volume restoration and the two out-of-band Secrets.
• Related runbook: ../runbooks/forgejo.md

8. Release and Change Notes

• Current deployed app version: forgejo 16.0.3 , postgres 18 (versioned-subdir storage layout under /var/lib/postgresql).
• Current chart version: N/A.
• Last significant change: 2026-09-02 production-readiness pass — shared Fleet/kustomize entry points, out-of-band secrets split, probes/resources/security contexts, ozilab Fleet wiring.
• Rollback reference: previous overlay revision in Git.