Add SCM Events for Branch Commit Pushes

[TemperingPick]

Is there any plans to add events for commit actions? I see that it currently only covers changes, repositories, and branch event, but nothing about events that happen within branches.

Is there an alternative I'm missing?

[afrittoli]

Hi @TemperingPick - thanks for this.

A way you could model this is to use the change merged event.

We use the change term because different systems use different terminology and workflows, i.e. GitHub / pull request, GitLab / merge request, Gerrit / change request. The various predicates of a change aim to give an implementation neutral set of events that can be adapted to the various workflows.

That said, there is dedicated field in the branch today to specify the branch, which seems to be something missing in the model.
@xibz @davidB @dsanyika WDYT?

[xibz]

We’ve actually struggled with this internally.

One issue is that a branch is mutable. A branch such as main may point to commit A at T1 and commit B at T2. If an event only identifies the branch by name, a consumer resolving that branch later may observe a different state than the one that existed when the event occurred.

So I think we need to represent not only the branch identity/name, but also the commit the branch pointed to at the time of the event. That gives the event a stable snapshot of the relevant source state.

There’s then a separate question around granularity: should commits themselves be modeled through dedicated events, or should commit information be incorporated into the existing change model?

I’m currently more inclined toward the latter. change already gives us the implementation-neutral abstraction across PRs, merge requests, change requests, etc., so it may make more sense to improve that model so it can describe the relevant commits rather than immediately introduce a separate commit-event lifecycle.

I think the important thing is distinguishing branch identity, branch state at the time of the event, and the change/commit topology associated with that occurrence.

[afrittoli]

We’ve actually struggled with this internally.

One issue is that a branch is mutable. A branch such as main may point to commit A at T1 and commit B at T2. If an event only identifies the branch by name, a consumer resolving that branch later may observe a different state than the one that existed when the event occurred.

So I think we need to represent not only the branch identity/name, but also the commit the branch pointed to at the time of the event. That gives the event a stable snapshot of the relevant source state.

+1

There’s then a separate question around granularity: should commits themselves be modeled through dedicated events, or should commit information be incorporated into the existing change model?

Until now we steered away from commit level events. A change could include a single commit but also multiple ones.
Having a list of commits might work. An alternative could be to use change events for individual commits when the use-case requires that granularity, and use links to connect the container-change to the commit-change.

[xibz]

Until now we steered away from commit level events. A change could include a single commit but also multiple ones.
Having a list of commits might work. An alternative could be to use change events for individual commits when the use-case requires that granularity, and use links to connect the container-change to the commit-change.

Yea, I’m in agreement there. Commit level events feel too granular for CDEvents.

One thing we need to balance is providing consumers with the signals they need without modeling every underlying implementation level occurrence as its own event. If we introduce commit events, a single change could produce a potentially large number of events, while only a relatively small set of consumers may actually need that level of granularity.

I think the alternatives you suggested are more attractive. We could include the relevant commits as an array on change.merged, or potentially use links where the relationship itself is important.

I’m particularly interested in the array or links approach because it lets us say, “this change was merged, and these were its constituent commits,” without promoting each commit to a first class SDLC occurrence.

[TemperingPick]

I looked at the change subject but felt it didn't map appropriately to the use case, since it seemed to focused more on merge events, not just branch events.

For example, a use case that I have is to trigger certain actions on updates to feature branches that won't ever be merge events. Another use case would be pushes to main that can bypass change events.

It feels a bit missing to not have update predicates on branch events for those use cases, even if there might be noisy. I would imagine that it would contain the branch subject, a before commit id, and an after commit id.

I'm new to the project so please let me know if I'm off base here but in our enterprise we would use these events significantly to run certain actions on specific branches.

[xibz]

Thanks, that helps clarify the gap you’re pointing at.

I think the part I’m still trying to understand is the concrete consumer use case. When you say you would use these events to “run certain actions on specific branches,” what kinds of actions are you referring to?

I ask because there are two slightly different things we could be modeling here:

• a low-level SCM occurrence such as a push/ref update, or
• an implementation-neutral SDLC occurrence that says “the source state represented by this branch changed from commit A to commit B.”

The second one feels potentially relevant to CDEvents, and your examples around feature branches and direct pushes to main do show a case that change.merged would not cover.

What I’m trying to avoid is introducing an event primarily as a normalized source control webhook if the consumers are really reacting to implementation-specific repository activity. Understanding what downstream behavior depends on this signal would help establish where that granularity boundary should be.

So a couple of concrete examples of what your consumers would trigger from a branch update would be really helpful.