Skip to content

forgejo Runbook

Metadata

Field Value
Service forgejo
Criticality Tier 2
Owner Platform / SCM owner
Namespace forgejo
Clusters local
Last validated 2026-05-20
Related service page ../services/forgejo.md

Trigger Conditions

  • Forgejo UI or Git traffic is unavailable.
  • Repository operations fail.
  • PostgreSQL becomes unhealthy.
  • Ingress or authentication middleware breaks the route.

1. Health Checks

kubectl -n forgejo get pods,svc,pvc,ingressroute
kubectl -n forgejo logs deploy/forgejo --tail=200
kubectl -n forgejo get statefulset

2. Troubleshooting Workflows

kubectl -n forgejo describe deploy forgejo
kubectl -n forgejo logs statefulset/forgejo-db --tail=100
kubectl -n forgejo describe ingressroute

Check DB auth, PVC attachment, and Traefik middleware references first.

3. Disaster Recovery

  1. Restore PostgreSQL state from backup or PVC snapshot.
  2. Restore application secrets.
  3. Reconcile forgejo/overlays/local.
  4. Validate UI and Git clone/push paths.

4. Scaling and Resource Management

kubectl -n forgejo top pod
kubectl -n forgejo describe deploy forgejo

Adjust app or DB resources in Git if repository traffic exceeds current limits.

5. Maintenance Procedures

  • Rotate admin and DB credentials.
  • Validate ingress and auth middleware after edge changes.
  • Recheck PVC ownership before node maintenance.

6. Rollback Strategy

  • Revert the overlay to the previous working revision.
  • Restore the DB snapshot if application schema or config changes failed.

7. Post-Incident Actions

  1. Add a changelog fragment for manual recovery.
  2. Update the Forgejo service page if topology or access changed.
  3. Extend this runbook if a new operational hazard was identified.