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
Two Forgejo runbooks plus the Authentik OAuth2 provider guide,
mirrored from the iCloud folder into the versioned repo.
Runbooks:
- forgejo-admin-recovery.md — fallback login when Authentik is down
using the local admin-local user (prohibit_login reset via SQL).
- forgejo-backup-restore.md — backup format, restore scenarios
(full / DB-only / single file), disaster recovery on new host.
Guides:
- authentik-oauth2-provider.md — reusable template for adding native
OIDC integrations in Authentik. First applied for Forgejo, ready
to reuse for OpenProject, Nextcloud, Grafana. Includes the
important launch-URL gotcha from ADR-0006.
Each category folder has a README.md with format conventions and
an index of the current documents.
Refs OP#1118
