Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Github-CDEvents Integration #47

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

RFC: Github-CDEvents Integration #47

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
195eda2
added github-events to cdevents rfc
rjtch Oct 2, 2024
464fd6a
added more specific webhook events
rjtch Oct 4, 2024
dca29a9
reviewed cd-event list
rjtch Nov 24, 2024
924e7bb
text and events reviewed
rjtch Dec 11, 2024
6bf7574
typo
rjtch Dec 11, 2024
4056899
typo
rjtch Dec 11, 2024
d6fd3fe
typo
rjtch Dec 11, 2024
e16f298
render as list
rjtch Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions rfc/github-cdevents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
## Github-CDEvents Integration

### Overview
The integration of CDEvents with Github is made by converting Github-events into CDEvents. This effort uses Github-Webhook generated events and translate them into CDEvents.
Github-events are to be converted into [CDEvents-Source Code Control Events](https://github.com/cdevents/spec/blob/v0.3.0/source-code-version-control.md)
using a custom plugin/adapter that will be responsible to translate [webhook-events](https://docs.github.com/en/webhooks/webhook-events-and-payloads) into CDEvents.

#### Convert the webhook-events
All events generated from the Github-Pipeline are captured in the [webhook-payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) and converted into CDEvent by the webhook-adapter.

### CDEvent github-webhook-tranlator
When installing plugins in the webhook adapter, the plugin name is used as path, with the resulting path being `<webhook adapter host>/translate/<plugin name>`.
The below list of [CDEvents-Source Code Control Events](https://github.com/cdevents/spec/blob/v0.3.0/source-code-version-control.md) will be mapped with corresponding Github-Webhook event types to translate.
Since this effort is to process webhook events, we consider processing the webhook-events
related to branch, repository and artifact. The [CDEvent-Spec](https://github.com/cdevents/spec/blob/v0.3.0/spec.md) does not have events for tags or release yet.


| Webhook/Github Event Type | CDEvent Type | Comments |
|:----------------------------|:------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| push | dev.cdevents.repository.created | A Git repository has been created from a template. |
| delete | dev.cdevents.branch.deleted | A Git branch or tag is deleted | | |
| create | dev.cdevents.branch.created | A Git branch or tag is created. |
| push | dev.cdevents.branch.deleted | A Git branch has been deleted. But to subscribe to only branch and tag deletions, use the delete webhook event. |
| push | dev.cdevents.change.updated | A commit/ commit tag is pushed. |
| pull_request | dev.cdevents.change.created | This event occurs when there is activity on a pull request. <details><summary>Actions</summary> {"Action type":{"opened"}</br> |
| pull_request | dev.cdevents.change.updated | This event occurs when there is activity on a pull request. <details><summary>Actions</summary> {"Action type":{"assigned", "auto_merge_disabled", "auto_merge_enabled", "closed", "converted_to_draft", "demilestoned", "dequeued", "enqueued", <br/>"archived", "labeled", "locked", "milestoned", "ready_for_review","reopened", "review_request_removed", "review_requested", "synchronized", "unassigned", "unlabeled", "unlocked"}</br> |
| pull_request_review_comment | dev.cdevents.change.reviewed | This event occurs when there is activity on a pull request review comment. <details><summary>Actions</summary> {"Action type":{"created", "reviewed", "commented"} |
| pull_request_review | dev.cdevents.change.reviewed | This event occurs when there is activity relating to a pull request review. <details><summary>Actions</summary> {"Action type":{"edited", "dismissed", "submitted"} </details> |
| pull_request_review_thread | dev.cdevents.change.reviewed | This event occurs when there is activity relating to a comment thread on a pull request. <details><summary>Actions</summary> {"Action type":{"resolved", "unresolved"} </details> |
| package/register_package | dev.cdevents.artifact.modified/registry_package | This event occurs when there is activity relating to GitHub Packages/registry. <details><summary>Actions</summary> {"Action type":{"updated"} </details> |
| package/register_package | dev.cdevents.artifact.published | This event occurs when there is activity relating to GitHub Packages/registry. <details><summary>Actions</summary> {"Action type":{"published"} </details> |

* Once mapped the CDEvent will be created using CDEvents Go-SDK and send to the configured `Events Broker URL`.
* The "Webhook/Github Event Type" is obtained by the `X-GitHub-Event` HTTP header.
* The "Actions", when specified can be obtained by the `.action` field from the payload, shared by all events.
* In cases where the same GitHub Event Type corresponds to multiple CDEvents, the specific CDEvent to produce is identified by additional fields in the source payload.
* The "CDEvents Type" refers to the [.context.type](https://github.com/cdevents/spec/blob/v0.4.1/spec.md#type-context) field in CDEvents.