GitHub Action Integration

Send CDEvents directly from GitHub workflows using the send-cdevents action.

• Integrate CDEvents into your CI/CD pipelines without webhooks or external infrastructure.
• Send custom CDEvents directly from your GitHub Actions workflows to any CDEvents consumer or HTTP endpoint.

CDEvents	From event
custom cdevents	workflow trigger
service.deployed	deployment success
test.finished	test completion
artifact.packaged	artifact build

References

• send-cdevents GitHub Action
• CDEvents Specification
• GitHub Actions Documentation

Overview

The send-cdevents GitHub Action provides a direct way to send CDEvents from your GitHub workflows to any CDEvents consumer or HTTP endpoint. Unlike webhook-based integrations, this action gives you full control over when and what events are sent, making it perfect for custom CI/CD scenarios.

While this documentation focuses on using the action with CDviz, the action works with any CDEvents-compatible system or HTTP endpoint that can receive JSON payloads.

The action supports all standard CDEvents types. For a complete list, see the CDEvents Specification.

Key Benefits

• Direct Integration: No need to configure webhooks or external services
• Custom Events: Send exactly the events you need, when you need them
• Universal Compatibility: Works with any CDEvents consumer or HTTP endpoint
• Workflow Control: Trigger events based on specific workflow conditions
• Secure: Uses GitHub's built-in secrets management

Quick Start

1. Basic Usage

Add the action to your workflow to send a CDEvent:

name: Send CDEvent
on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Send deployment event
        uses: cdviz-dev/send-cdevents@v1
        with:
          data: |
            {
              "context": {
                "version": "0.4.1",
                "source": "github.com/${{ github.repository }}",
                "type": "dev.cdevents.service.deployed.0.1.4"
              },
              "subject": {
                "id": "myapp/production",
                "type": "service",
                "content": {
                  "version": "${{ github.sha }}",
                  "environment": "production"
                }
              }
            }
          url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}

2. With Authentication

If your CDEvents endpoint requires authentication, use custom headers:

- name: Send authenticated event
  uses: cdviz-dev/send-cdevents@v1
  with:
    data: |
      {
        "context": {
          "version": "0.4.1",
          "source": "github.com/${{ github.repository }}",
          "type": "dev.cdevents.artifact.packaged.0.1.1"
        },
        "subject": {
          "id": "pkg:...",
          "type": "artifact",
          "content": {
            "change": {
              "id": "${{ github.sha }}"
            }
          }
        }
      }
    url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}
    headers: |
      Authorization: Bearer ${{ secrets.CDEVENTS_AUTH_TOKEN }}

3. With Signature

- name: Send authenticated event
  uses: cdviz-dev/send-cdevents@v1
  with:
    data: |
      {
        "context": {
          "version": "0.4.1",
          "source": "github.com/${{ github.repository }}",
          "type": "dev.cdevents.artifact.packaged.0.1.1"
        },
        "subject": {
          "id": "pkg:...",
          "type": "artifact",
          "content": {
            "change": {
              "id": "${{ github.sha }}"
            }
          }
        }
      }
    url: ${{ secrets.CDEVENTS_ENDPOINT_URL }}
    config: |
      [sinks.http.headers.x-signature-256]
      type = "signature"
      algorithm = "sha256"
      prefix = "sha256="
    env:
      CDVIZ_COLLECTOR__SINKS__HTTP__HEADERS__X_SIGNATURE_256__TOKEN: ${{ secrets.CDEVENTS_ENDPOINT_TOKEN }}

Configuration

Parameters

Parameter	Required	Description	Example
data	Yes	JSON data containing the CDEvent	See examples above
url	No	HTTP endpoint for sending events	https://events.example.com/cdevents
config	No	TOML configuration for advanced settings	See advanced section
headers	No	Additional HTTP headers (one per line)	Authorization: Bearer token
version	No	cdviz-collector container version	latest (default)

Data Input Formats

The data parameter accepts multiple formats:

• Direct JSON: Inline JSON string (as shown in examples above)
• From file: @path/to/file.json - reads JSON from a file
• From stdin: @- - reads JSON from standard input

CDEvent Structure

Your JSON data should follow the CDEvents specification structure.

let the action generate `context.id` and `context.timestamp`

It's recommended to let the action generate context.id and context.timestamp automatically by omitting these fields from your JSON. The action will populate them with appropriate values (id based on content of the event and current timestamp).

Example minimal structure:

{
  "context": {
    "version": "0.4.1",
    "source": "github.com/myorg/myrepo",
    "type": "dev.cdevents.service.deployed.0.1.4"
  },
  "subject": {
    "id": "myapp/production",
    "type": "service"
  }
}

Complementary: GitHub Webhook Integration

For comprehensive GitHub activity tracking, you can use the GitHub Webhook integration alongside this GitHub Action.

These approaches can be used together for complete event coverage:

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

Recommended combinations:

• GitHub Action only: Custom events for specific workflows with full control
• Webhooks only: Complete GitHub activity tracking with automatic setup
• 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 webhook setup instructions, see the GitHub Webhook Integration Guide.

Advanced Configuration

As the action is a wrapper over cdviz-collector send, you can configure it to use:

• transformers
• all kind of sinks, except those running in server mode (like SSE) and when available (Kafka, NATS, ...)