Design a Git Branch Change Event Capture System
Capture every accepted branch ref change as one durable, ordered event that internal consumers can read and replay.
Problem statement
For this exercise, assume a hosted Git service whose Git servers accept pushes and API calls that create a branch, move it to a new commit (including a force-push), or delete it.
Design an event capture system that turns every accepted change to a branch ref into exactly one durable branch event, and lets internal consumers such as webhook delivery, audit history, and CI triggers read those events in order for each repository and replay them from a saved position.
A change that the Git server rejects must never produce an event, and an accepted change must never be lost, even if a server crashes right after accepting it. Running the consumers themselves, git object storage, and repository permissions are outside scope.
What to build
- Every accepted branch create, update (including force-push), or delete becomes exactly one durable event with the repository, branch, old and new commit IDs, actor, and time; rejected changes produce no event.
- Consumers receive a repository's branch events in the order the ref changes were committed, at least once, each with a stable event ID they can deduplicate on.
- A consumer can pick up where it stopped, or replay one repository's recent branch events from an earlier saved position, for up to 30 days.
At scale
- For this exercise, assume about 50,000 accepted ref changes per second at peak across about 100 million repositories, with a few very busy repositories producing hundreds per second.
- For this exercise, assume 99% of events are readable by consumers within 5 seconds of the ref change, and events are retained and replayable for 30 days.
- For this exercise, assume no accepted ref change may be lost if one Git server or one availability zone fails, and a slow or failed consumer must not slow down ref updates or other consumers.