neiam /gitgud

Git Gud

Plan: audit log decisions — log lines kept, IPs for instance admins, sudo to view, no team-admin access

36965b5 · Gabriel Morell · 2026-10-20 21:09

3 files +21 -4

modified docs/plans/org-audit-log.md

+21 −4

@@ -1,6 +1,6 @@

1	1	# Plan: an audit log for organizations, repositories and the instance
2	2
3		−Status: draft — the open questions at the end need answers before slice 2.
	3	+Status: draft — decisions recorded below (2026-10-20); retention still to confirm.
4	4	Independent of the CI plans. Supersedes the log lines added in 77def2d
5	5	("Secrets: changing a secret or variable leaves a line in the log") and
6	6	closes item 12 of `security-review-ci.md` ("Missing audit logging for

@@ -322,9 +322,10 @@ flash; out-of-order segments patch to the canonical order.

322	322	- `GitGudWeb.AuditLive.Admin`: everything, plus an org filter and the
323	323	instance-only rows.
324	324
325		−Who sees what: org view — org admins and instance admins; repo view — repo
326		−admins (owner, org admins, admin-permission team members); admin view —
327		−`is_admin`. Members who aren't admins see nothing.
	325	+Who sees what: org view — org admins and instance admins; repo view — the
	326	+owner of a personal repo, or an org admin for an org repo (team admins
	327	+don't); admin view — `is_admin`. Members who aren't admins see nothing.
	328	+Every view needs sudo mode; IP and user agent show only in the admin view.
328	329
329	330	## 4. API and CLI (optional, slice 10)
330	331

@@ -455,6 +456,22 @@ Same table: `organization_id`/`repository_id` nil, `subject_user_id` and

455	456	- One commit per slice in the repository's message style.
456	457	- Not pushed without asking.
457	458
	459	+## Decisions (2026-10-20)
	460	+
	461	+- Log line per entry: yes. `Audit` keeps one `Logger.notice` per row
	462	+ after commit (open question 1).
	463	+- Retention: answered "yes" to "forever or 365 days" — to confirm
	464	+ which. Until then slice 1 ships the `audit.retention_days` setting with
	465	+ `nil` (keep everything) as the default, so nothing is pruned on a guess.
	466	+- IP and user agent: instance admins only. Org and repo views, and the
	467	+ API, never show them; `/admin/audit` does (open question 3).
	468	+- Viewing the log requires sudo mode. All three views mount with
	469	+ `{GitGudWeb.UserAuth, :require_sudo_mode}` and re-check it in
	470	+ `handle_params` (open question 5).
	471	+- Repo admins who aren't org admins don't see an org repo's log. The
	472	+ repo view is for repos without an org (the owner) and for org admins;
	473	+ for an org repo it needs `Organizations.org_admin?/2` (open question 6).
	474	+
458	475	## Open questions
459	476
460	477	1. Keep a `Logger.notice` per entry (recommended, so log shipping and SIEMs

Parents: 678b57f