When a new user logs in via Authentik OIDC for the first time,
Forgejo tries to fetch the 'picture' claim as an avatar — but
Authentik delivers a 'data:image/svg+xml;base64,...' URL that
Forgejo can't store. Result: DB has an avatar hash but no file,
so /avatars/<hash> returns 404, the <img> is in broken state,
and the activity page's canvas renderer crashes with
'drawImage on broken state'.
Fix (per user, after first login):
UPDATE "user" SET avatar = '', use_custom_avatar = false
WHERE lower_name = '<name>';
Triggers Forgejo's default identicon generation, which works.
This commit:
- Adds ADR-0007 with full root cause + three rejected alternatives
- Updates docs/adr/README.md index
- Extends stacks/forgejo/Agent.md 'Known Gotchas' with the fix
- Appends the fix to docs/runbooks/forgejo-admin-recovery.md
Applied for user 'bw' already on 2026-04-12.
Refs OP#1119
Root Agent.md and stacks/forgejo/Agent.md had stale references to
"docs live in iCloud, will be mirrored in M7.3". Now M7.3 is done,
so the briefings point to docs/adr/ and docs/runbooks/ directly
with relative links that render as clickable in the Forgejo web UI.
The iCloud folder stays around for loose notes and credentials
that cannot go into a public repo, but the primary source of truth
for ADRs / runbooks / guides is now this repo.
Refs OP#1118
First stack mirrored 1:1 from /opt/ai-apps/forgejo/ on the server.
Includes docker-compose.yml (forgejo + postgres 16), .env.example
template (NO real secrets), backup.sh (nightly pg_dump + tar), plus
Agent.md and README.md.
Known gotchas documented in Agent.md:
- Volume mount on /data not /var/lib/gitea
- SSH port 2222 in container (system sshd occupies 22)
- OIDC config lives in DB table login_source, not app.ini
Refs OP#1119
