Forgejo — Setup

Git forge and CI/CD platform. Forgejo (LXC 100) runs the git server; Forgejo Runner (LXC 101) executes Actions workflows. All deployments in this homelab go through Forgejo Actions.

Infrastructure

Component	Host	LXC ID	Internal IP	URL
Forgejo	Alpine LXC	100	192.168.1.69:3000	https://git.eva-00.network
Forgejo Runner	Alpine LXC	101	192.168.1.211	—

Observability

Logs

Forgejo application logs and Forgejo Runner logs are collected via Grafana Alloy and shipped to Loki.

Component	Log Source	Loki Query	Stream Filtering
Forgejo server	`/var/log/forgejo/gitea.log` (LXC 100)	`{job="forgejo"}`	Add `\\|= "error"` to find errors, `\\|= "warn"` for warnings
Forgejo Runner	`/var/log/forgejo-runner.log` (LXC 101)	`{job="forgejo-runner"}`	Same as above
Forgejo Actions logs	Compressed `.log.zst` in action directory	`{job="forgejo-actions"}`	Decompressed via Python cron script every 2 minutes

Access: Grafana → Explore → Loki → Enter query above

Metrics

Metric	Query	Purpose
Forgejo uptime	`{container="forgejo"}` returns data	If absent, service is down or not logging
Runner connection	`{job="forgejo-runner"}` has recent logs	If logs stop flowing, runner is disconnected from host

Access: Grafana → Explore → Loki (to check log flow) → No Prometheus metrics exported by default

IaC

Artifact	Path
Forgejo playbook	`ansible/playbooks/forgejo.yml`
Runner playbook	`ansible/playbooks/forgejo-runner.yml`
Forgejo workflow	`.forgejo/workflows/forgejo.yml`
Runner workflow	`.forgejo/workflows/forgejo-runner.yml`

Runner config

Runner config lives at /root/.runner on LXC 101. Contains: instance URL, registration token, and labels.

The runner SSH key (/root/.ssh/id_ed25519 on LXC 101) is authorised on the Proxmox host (chizuru) so workflows can run Ansible playbooks via SSH.

Bot account

A dedicated bot user exists for CI workflow dispatch (avoids using the personal holo token).

Token stored in Vault at secret/forgejo-bot → key token
Collaborator on holo/homelab with write permission
Reprovisioned via: Forgejo Actions → Create Forgejo Bot Account → Run workflow
To regenerate the token: delete secret/forgejo-bot from Vault, then re-run the workflow

PocketID SSO

Forgejo uses native OIDC via the openidConnect provider. The auth source is managed by ansible/playbooks/forgejo.yml — it reads credentials from Vault and configures the auth source via forgejo admin auth add-oauth / update-oauth.

Secrets (stored in Vault):

secret/forgejo   → pocketid_client_id, pocketid_client_secret

Important: When first enabling SSO, ensure your Forgejo admin account email exactly matches the email in your PocketID profile ([email protected]). If they differ, SSO will create a new separate account instead of signing into the existing admin account.

Renaming the Forgejo URL

Performed March 2026: code.eva-00.network → git.eva-00.network. Steps to repeat if the URL changes again:

1. Update all repo references

grep -r "old.domain" /path/to/homelab --exclude-dir=.git -l \
  | xargs sed -i 's/old.domain/new.domain/g'

Files affected: Caddyfile, all Forgejo workflow clone URLs, Glance config, Gatus config, docs.

2. Update Forgejo app.ini (LXC 100)

ssh [email protected] "pct exec 100 -- sed -i 's|old.domain|new.domain|g' /etc/forgejo/app.ini"
ssh [email protected] "pct exec 100 -- rc-service forgejo restart"

Or just run the Forgejo IaC playbook — it manages DOMAIN, SSH_DOMAIN, and ROOT_URL.

3. Update the Forgejo runner registration (LXC 101)

ssh [email protected] "sed -i 's|old.domain|new.domain|g' /root/.runner"
ssh [email protected] "rc-service forgejo-runner restart"

4. Update local git remote

git remote set-url origin https://new.domain/holo/homelab.git
security add-internet-password -s new.domain -a <user> -w <token> -U

5. Redeploy Caddy

If Caddy can't be reached via Forgejo Actions (chicken-and-egg), run the playbook locally:

cd ansible && ansible-playbook -i inventory.yml playbooks/caddy.yml

Caddy will automatically obtain a TLS cert for the new domain on first request (Let's Encrypt HTTP-01 challenge). No manual cert management needed — DNS wildcard *.eva-00.network handles resolution.

6. Redeploy any services that failed during the transition (workflows that tried to clone via the old URL) by triggering them manually from the Forgejo UI: Actions → select workflow → Run workflow.