gitea-heatmap-sidecar

A tiny HTTP service that exposes daily contribution counts for an allowlisted Gitea user — including private repo activity — for rendering a GitHub-style heatmap on a public profile page.

Stock Gitea (and Forgejo) intentionally do not expose private contribution counts to anonymous viewers. This is a sidecar workaround: read directly from Gitea's action table with a read-only DB user, return per-day counts as JSON, and let a custom profile template render the squares client-side.

What it shows / what it doesn't

• ✅ Daily counts (the green squares)
• ✅ Hover tooltips with the date, count, and repo names
• ❌ Commit messages, branches, file content — none of that ever leaves the database.

Architecture

[anonymous visitor] → GET /didericis (Gitea)
                        ↓ profile.tmpl override loads
                     <script> fetches https://heatmap.dideric.is/heatmap/didericis.json
                        ↓
                     [this service] → SELECT FROM action WHERE act_user_id=? → JSON

Setup

See docs/truenas.md for the full TrueNAS SCALE setup guide (Custom App Wizard + Gitea template override).

Op type reference

Gitea's action.op_type is an integer enum. Defaults are commits-only (5,9,18), which is the closest analog to what GitHub counts as a "contribution" in their heatmap. Common values:

Value	Meaning
1	Create repo
5	Push commits
6	Create issue
7	Create pull request
9	Push tag
11	Merge pull request
18	Mirror sync push
24	Publish release

Set OP_TYPES=5,6,7,9,11,18,24 for a more inclusive count.

Endpoints

• GET /heatmap/{username}.json — JSON [{"date":"YYYY-MM-DD","count":N,"repos":["name", ...]}, ...] for the past ~53 weeks. 1-hour cache header.
• GET /healthz — 200 if the DB is reachable, 503 otherwise.

Maintenance

• Gitea schema changes. The query reads from "action" and "user". These tables have been stable for many Gitea versions. After each Gitea upgrade, hit /healthz and the JSON endpoint to confirm.
• Template drift. The harder part. Gitea's profile.tmpl does change between versions — diff the new upstream against your override on each upgrade and re-merge the snippet.
• Cache. 1-hour Cache-Control header keeps load trivial. Drop to 5 minutes for snappier updates if needed; the underlying query is cheap thanks to the existing index on (user_id, act_user_id, created_unix) added in Gitea 1.24.

Local dev

go run . # requires DATABASE_URL and ALLOWED_USERS in env

go build ./... produces a binary named gitea-heatmap-sidecar (derived from the module name). The Dockerfile overrides this with -o /heatmap; the two names differ but refer to the same program.

On NixOS:

nix-shell -p go_1_23 postgresql

Limitations

• Postgres only. MySQL support would mean swapping to_timestamp(...) for FROM_UNIXTIME(...) and adjusting identifier quoting — straightforward but not done here.
• Single-tenant by allowlist. The service is meant for a personal Gitea instance with a small known set of users opting in. Don't expose it to arbitrary usernames; that would leak private activity counts for users who haven't consented.
• No auth on the JSON endpoint by design — the data is intentionally public.

License

MIT