GitHub WebHook Integration

Collect GitHub events (via webhooks), transform them to cdevents.

• Github tracks all changes to repositories, issues, pull requests, releases, workflows, and more. And it notifies a webhook about these changes.
• cdviz-collector transforms these events to cdevents, and sends them to the database, listeners,...

CDEvents	From event
artifact.published	package.published
artifact.published	release.published
pipelineRun.queued	workflow_run.requested
pipelineRun.started	workflow_run.in_progress
pipelineRun.finished	workflow_run.completed
taskRun.started	workflow_job.in_progress
taskRun.finished	workflow_job.completed
ticket.created	issue.opened
ticket.closed	issue.closed
ticket.updated	issue.*
branch.created	branch.
change.created	pull_request.opened
change.{merged,abandoned}	pull_request.closed
change.updated	pull_request.*
change.reviewed	pull_request_review.submitted

References

• GitHub Webhooks and Events
• Source code of the transformation of GitHub Webhooks to cdevents
• Examples of cdevents converted from github's events

Configuration

Setting Up cdviz-collector's side

Setting up cdviz-collector.toml to receive GitHub events involves defining a webhook source in the collector configuration file. Below is an example configuration snippet:

# Remote transformers repository configuration
[remote.transformers-community]
type = "github"
owner = "cdviz-dev"
repo = "transformers-community"

[sources.github_webhook]
enabled = true
transformer_refs = ["github_events"]

[sources.github_webhook.extractor]
type = "webhook"
id = "000-github"
headers_to_keep = []

[sources.github_webhook.extractor.headers]
"x-hub-signature-256" = { type = "signature", signature_encoding = "hex", signature_on = "body", signature_prefix = "sha256=", token = "changeme" }


# Transformer from transformers-community repository
[transformers.github_events]
type = "vrl"
template_rfile = "transformers-community:///github_events/transformer.vrl"

The signature field is used to verify the authenticity of the webhook payload. You should replace "changeme" with your actual secret token that you set in your GitHub webhook configuration.

The template_rfile references the VRL (Vector Remap Language) file from the transformers-community repository that contains the transformation logic for converting GitHub webhook events into CDEvents. The source code can be found at github_events/transformer.vrl.

For more details on remote transformers, including using specific tags or commits, see the Transformers documentation.

Setting Up GitHub Webhook

To configure the GitHub integration, you need to set up a webhook in your GitHub repository or in your GitHub Organization. Here are the steps to do that:

1. Go to your GitHub repository or organization settings.
2. Navigate to the "Webhooks" section.
3. Click on "Add webhook".
4. In the "Payload URL" field, enter the URL where your cdviz-collector is running, followed by /webhook/{id_of_webhook_extractor}. For example: http://your-collector-url/webhook/000-github.
5. Set the "Content type" to application/json.
6. In the "Secret" field, enter the secret token that you specified in your cdviz-collector.toml configuration.
7. Select the events you want to trigger the webhook. You can choose "Let me select individual events" and select the events you are interested in, or you can select "Send me everything" to receive all events.
   • Branch or tag creation
   • Branch or tag deletion
   • Issues
   • Packages
   • Pull requests
   • Pull request reviews
   • Releases
   • Repository
   • Workflow jobs
   • Workflow runs
8. Make sure the "Active" checkbox is checked.
9. Click on "Add webhook" to save the configuration.

Complementary: GitHub Action Integration

For enhanced control and custom events, you can also use the GitHub Action integration alongside or instead of webhooks.

These approaches can be used together for comprehensive event coverage:

Feature	Webhook Integration	GitHub Action
Setup	Configure webhook + collector	Add action to workflow
Event Control	All GitHub events	Custom events only
Custom Data	Limited to webhook payload	Full control
Timing	Real-time	Workflow-controlled
Maintenance	Central configuration	Per-workflow setup

Recommended combinations:

• Webhooks only: Complete GitHub activity tracking with automatic setup
• GitHub Action only: Custom events for specific workflows with full control
• Both together: Comprehensive GitHub events (webhooks) + custom workflow data (actions)

Example combined use case: Use webhooks to track all repository activity automatically, while adding GitHub Actions to specific deployment workflows to send detailed deployment context and custom metrics.

For step-by-step instructions, see the GitHub Action Integration Guide.