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 2 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
58 changes: 58 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,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)
rjtch marked this conversation as resolved.
Show resolved Hide resolved
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.
rjtch marked this conversation as resolved.
Show resolved Hide resolved

### 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.
rjtch marked this conversation as resolved.
Show resolved Hide resolved
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.
rjtch marked this conversation as resolved.
Show resolved Hide resolved


| CDEvent Type | Webhook/Github Event Type | Comments |
|:---------------------------------|:----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| dev.cdevents.repository.forked | fork | A user forks a repository. (should be defined in the spec) |
rjtch marked this conversation as resolved.
Show resolved Hide resolved
| dev.cdevents.repository.imported | repository_import | when a new repository is imported to Github. (should be defined in the spec) |
rjtch marked this conversation as resolved.
Show resolved Hide resolved
| 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> | |
rjtch marked this conversation as resolved.
Show resolved Hide resolved
| 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"} |
rjtch marked this conversation as resolved.
Show resolved Hide resolved
| 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`
rjtch marked this conversation as resolved.
Show resolved Hide resolved