ADR-0011: Commit the event log to Git at checkpoints, onto a ref of its own
- Status: Accepted
- Date: 2026-10-17, accepted 2026-10-18
- Authors: Epitrop maintainers
Context
The event log (architecture, Event log) is a directory of plain files in a Git working tree, written only by the control plane. Nothing commits it: its history lives only on the disk it was written to. Issue #58 asks for batched commits at checkpoint boundaries, made by the control plane under its own identity, with Git and hooks kept off the append path. Compaction, the next step of #58, will move segments out of events/ only once a commit holds them, so it needs these commits first.
The commits must not disturb the operator. The log usually lies in a repository the operator works in. A commit made with git commit would run the operator's commit hooks, take whatever the operator has staged, fail on a conflicted index and move the checked-out branch.
Decision
-
The log is committed at every checkpoint, when enabled. With
event_log.git.enabled, the units service callsWriter.RecordInGit(internal/eventlog/gitrecord.go) after it writes a checkpoint and rotates the log at a status change. The keys areenabled(defaultfalse),ref(defaultrefs/epitrop/events),author_nameandauthor_email(both required when enabled) andtimeout_seconds(default 30, from 1 to 300), which bounds the Git commands of one commit together. A failed commit is recorded on the trace span and tried again at the next checkpoint. Appends never wait for Git. -
The commit holds the log byte for byte. Under the log lock,
RecordInGitstores every regular file inevents/,events/segments/andcheckpoints/<name>/as a blob withgit hash-object --no-filters, so neither a clean filter nor line-ending conversion changes a record. Names that start with a dot (the lock file, the temporary files of an interrupted write) stay out, and so does every other file in the log directory. The tree's paths are relative to the log directory. -
The commit goes to a ref nothing checks out, built with Git's plumbing.
RecordInGitfills a private index in a temporary directory, writes the tree, and makes the commit withgit commit-treeon top of the commit the ref names. When the ref already holds that tree it makes no commit. It moves the ref withgit update-refand the old value it built on, so a ref another writer moved meanwhile is refused, not overwritten. The operator's index, working tree and branch are never touched, and no commit hook runs. Git runs with the caller'sGIT_*variables and the global and system configuration dropped (internal/gitexec, shared with the slot runner), and the repository's own configuration still applies; areference-transactionhook the repository declares runs on the ref update, as it does for every ref update. -
Git does not sign the commit. Every record and checkpoint it holds carries its own Ed25519 receipt, so the content is proven without a commit signature, and no further key is needed. The author and committer are the configured identity; the dates come from the log's clock.
Consequences
- With
enabledset, the log's history is kept in the repository's object store onrefs/epitrop/events. Pushing that ref is a separate step that this record does not cover. - A log directory outside any Git repository fails the commit with the path; the log itself is unaffected.
- A crash during a commit leaves the log and the ref as they were, with at most objects no ref names, which
git gcremoves. - Compaction can now require a segment to be held by a commit before it leaves
events/(#58).
Alternatives considered
- Committing onto the checked-out branch with
git commit --only. Rejected: it runs the operator's commit hooks, races what the operator has staged, fails on a conflicted index and mixes the log's commits into the operator's history. - Signing the commits with a key of their own. Rejected for now: it adds a key the operator has to manage and a way for the commit to fail, and signs again what every record already proves.
git addwith a private index. Rejected: it applies clean filters and line-ending conversion, so the committed bytes could differ from the log's.
Verification
internal/eventlog/gitrecord_test.go, TestStatusChangeRecordsTheLogInGit in internal/units/checkpoint_test.go, TestRunUnitsSetRecordsTheLogInGitWhenEnabled in cmd/epitropctl/units_test.go, and the event_log.git cases in internal/config/config_test.go. Each check was shown failing on a planted defect: a clean filter applied, dot files committed, checkpoints left out, the operator's index used, a ref update without its old value, a commit made for an unchanged log, a commit without its parent, the private index left behind, no log lock, no validation, a units service that never commits, a command that does not pass the setting on, an author left optional, and an open ref pattern.