[Initiative] gRPC GitEvent Notification Stream from gitstore-git-service to gitstore-api

[juliuskrah]

Summary

Define the gRPC notification stream from gitstore-git-service to gitstore-api so the API can react to Git changes without WebSockets. The stream should carry commit/ref transition events and provide the control-plane trigger for sync and admission handling.

In Scope

• Define a GitEvent gRPC payload contract for ref changes, old/new SHA values, and event type
• Implement a server-streaming notification path from git-service to API
• Route events through the stream so the API/controller can decide what to do with commerce objects. Some events to consider where it makes sense for the current/future architecture
  • push / ref updated
  • branch created
  • branch updated
  • branch force-pushed
  • branch deleted
  • tag created
  • tag moved / tag updated
  • tag deleted
  • default branch changed
  • protected branch rejected
  • pre-receive rejected / push rejected
  • release created
  • mirror sync . bulk ref update
  • notes updated
  • replace ref updated
  • custom ref updated
  • etc
• Add contract tests for event delivery, reconnect behaviour, and event typing
• Document the event flow and operational expectations across the two services

Out of Scope

• The hydration and live-promotion logic itself (tracked separately)
• Replacing Git wire protocol handling
• UI notifications or browser-based realtime updates
• Authentication/authorisation policy design

Acceptance Criteria

• gitstore-git-service emits ref-change events to gitstore-api over gRPC
• Event payloads include ref, old SHA, new SHA, and event type
• API consumers can react to event notifications
• Lost connection / reconnect behavior is covered by automated tests
• Event documentation explains how stream notifications feed Sync Controller processing
• No WebSocket dependency is required for control-plane notifications

Implementation Notes

This stream is the control-plane equivalent of a watch mechanism: the git-service tells the API that Git state changed, but the API remains responsible for interpreting and materialising that change. Keeping the notification channel on gRPC preserves a clean service boundary and aligns with the rest of the Git-service decoupling work. The stream should be minimal and event-oriented, not a transport for business logic.

Thoughts: Attach this to a phase similar to admission_control_phase=post-receive, schema_validation_phase=pre-receive, event_notification_phase=??
When multiple phases attach to the same hook, they are run in parallel.

The API can decide what to do with the events; such as publishing it as part of watch semantics for controllers. A Release Controller reacting to tag created events could verify the tag target is reachable from the admitted branch,
then marks matching resources as Published=True. See #314

Dependencies

• Depends on: [Initiative] Decouple API from Git Storage via gRPC Git Service #65 (gRPC Git Service boundary)
• Related: [Initiative] Tag-Gated Sync Controller for Atomic Release Promotion #132, [Initiative] Controller Watch API with resourceVersion Resume #131, [Initiative] API Admission Controller (Validating Phase Only) #123, [Initiative] Git Event Publication and Admission Integration #169

[juliuskrah]

Supersedes #66