diff --git a/rfc/github-cdevents.md b/rfc/github-cdevents.md new file mode 100644 index 0000000..d827559 --- /dev/null +++ b/rfc/github-cdevents.md @@ -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 `/translate/`. +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.
Actions {"Action type":{"opened"}
| +| pull_request | dev.cdevents.change.updated | This event occurs when there is activity on a pull request.
Actions {"Action type":{"assigned", "auto_merge_disabled", "auto_merge_enabled", "closed", "converted_to_draft", "demilestoned", "dequeued", "enqueued",
"archived", "labeled", "locked", "milestoned", "ready_for_review","reopened", "review_request_removed", "review_requested", "synchronized", "unassigned", "unlabeled", "unlocked"}
| +| pull_request_review_comment | dev.cdevents.change.reviewed | This event occurs when there is activity on a pull request review comment.
Actions {"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.
Actions {"Action type":{"edited", "dismissed", "submitted"}
| +| pull_request_review_thread | dev.cdevents.change.reviewed | This event occurs when there is activity relating to a comment thread on a pull request.
Actions {"Action type":{"resolved", "unresolved"}
| +| package/register_package | dev.cdevents.artifact.modified/registry_package | This event occurs when there is activity relating to GitHub Packages/registry.
Actions {"Action type":{"updated"}
| +| package/register_package | dev.cdevents.artifact.published | This event occurs when there is activity relating to GitHub Packages/registry.
Actions {"Action type":{"published"}
| + +* 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.