RFC: Github-CDEvents Integration #47
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| ## 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 utilizes two types of events: the github-event and the issue-event. These 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 github-event to CDEvent translator. | ||
|
|
||
| ### Github webhook | ||
| On github, there are different types of webhooks: organization, repository, marketplace, sponsors and app webhook. | ||
| - Organization webhooks can subscribe to events that happen in all repositories owned by the organization. They can also subscribe to events that happen at the organization level that are outside of any particular repository. | ||
| - Marketplace webhook is the one that subscribes to events relating to an app that you published in GitHub Marketplace. | ||
| - Sponsors webhook is the kind of webhook that subscribe to events related to GitHub Sponsors. | ||
| - App webhook is a more generic webhook that can be configured to receive specific events that occur in a repository or organization that the app has been granted access to. | ||
|
|
||
| In this effort, we will focus on repository webhook because we want to be able to process events happening inside a repository. | ||
|
|
||
| #### Create a repository webhook | ||
| We have a [public project](https://github.com/rjtch/nodejs-webhook-server) on our github-account that is a simple nodejs-server capable to receive webhook-event (But any other server can be used for this end). | ||
| As webhook server we use [Hookdeck](https://hookdeck.com/webhooks/platforms/tutorial-github-webhooks). After everything is well configured we can start the webhook server together with our node-js-server. | ||
|
Comment on lines
+19
to
+20
There was a problem hiding this comment. I thought this was about cdevents/webhook-adapter#2. |
||
|
|
||
| ### Configure webhook | ||
| Everything concerning the webhook's configuration is explained in the Hookdeck [quickstart](https://hookdeck.com/webhooks/platforms/tutorial-github-webhooks) tutorial. | ||
| ```config | ||
| [remote "github-events"] | ||
| Dashboard = https://console.hookdeck.com | ||
| Source: https://hkdk.events/75yvzpqic09vvw | ||
| Connections: github -> github_to_cli-github forwarding to /github-webhooks-endpoint | ||
| Secret: 1234ABCD | ||
| ``` | ||
| for additional information you can refer to the [Hookdeck](https://hookdeck.com/webhooks/platforms/tutorial-github-webhooks) configuration page and the | ||
| [github-webhook](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks) page. | ||
|
|
||
| ### CDEvent github-webhook-tranlator | ||
|
|
||
| A new REST endpoint `/github-events` will be implemented to receive all github-events and translate them to CDEvents. | ||
| 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](https://docs.github.com/en/webhooks/webhook-events-and-payloads), we consider processing the webhook-events | ||
| related to branch, repository, deployment 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. | ||
|
|
||
|
|
||
| | CDEvent Type | Webhook/Github Event Type | Comments | | ||
| |:---------------------------------|:----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | dev.cdevents.repository.forked | fork | A user forks a repository. (should be defined in the spec) | | ||
|
There was a problem hiding this comment. We could use the |
||
| | dev.cdevents.repository.imported | repository_import | when a new repository is imported to Github. (should be defined in the spec) | | ||
|
There was a problem hiding this comment. I wonder if we could use |
||
| | dev.cdevents.repository.* | repository | This event occurs when there is activity relating to repositories. <details><summary>Actions</summary> {"Action type":{"created", "modified", "deleted", "edited", "privatized", "publicized", "renamed", "transfered", "unarchived", "archived"}</br> | | | ||
|
There was a problem hiding this comment. We should map these to CDEvents that exist where possible:
|
||
| | dev.cdevents.repository.created | push | A Git repository has been created from a template. | | ||
| | dev.cdevents.branch.deleted | delete | A Git branch or tag is deleted | | | | ||
| | dev.cdevents.branch.created | create | A Git branch or tag is created. | | ||
| | dev.cdevents.branch.deleted | push | A Git branch has been deleted. But to subscribe to only branch and tag deletions, use the delete webhook event. | | ||
| | dev.cdevents.change.updated | push | A commit/ commit tag is pushed. | | ||
| | dev.cdevents.change.* | pull_request | 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", "edited", "enqueued", <br/>"archived", "labeled", "locked", "milestoned", "opened", "ready_for_review","reopened", "review_request_removed", "review_requested", "synchronized", "unassigned", "unlabeled", "unlocked"}</br> | | ||
| | dev.cdevents.change.* | pull_request_review_comment | This event occurs when there is activity on a pull request review comment. <details><summary>Actions</summary> {"Action type":{"created", "reviewed", "commented"} | | ||
|
Comment on lines
+52
to
+53
There was a problem hiding this comment. We need to map as much as possible events from GitHub to events that exist in CDEvents. |
||
| | dev.cdevents.change.* | pull_request_review | This event occurs when there is activity relating to a pull request review. <details><summary>Actions</summary> {"Action type":{"edited", "dismissed", "submitted"} </details> | | ||
| | dev.cdevents.change.* | pull_request_review_thread | 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> | | ||
| | dev.cdevents.artifact.* | package/registry_package | This event occurs when there is activity relating to GitHub Packages/registry. <details><summary>Actions</summary> {"Action type":{"published", "updated"} </details> | | ||
|
|
||
| Once mapped the CDEvent will be created using CDEvents SDK(Java/Go) and send to the configured `Events Broker URL` | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've not seen the distinction
github-eventvsissue-eventbefore. Do you have a link to the relevant GitHub docs?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Her is the link of issue event https://docs.github.com/en/rest/using-the-rest-api/issue-event-types?apiVersion=2022-11-28