Configure the GitHub Events Module plugin

Configure GitHub webhooks to trigger real-time updates for GitHub Discovery and organizational data.

Before you begin

  • You have added your GitHub integration credentials in the app-config.yaml file.
  • You have defined the schedule.frequency in the app-config.yaml file as longer time period, such as 24 hours.
  • For GitHub Discovery only: You have enabled GitHub Discovery.
  • For GitHub Organizational Data only: You have enabled Github Authentication with user ingestion.

About this task

Learn how to configure Events Module for use with the RHDH GitHub Discovery feature and GitHub organization data.

Procedure

  1. Add the GitHub Events Module to your dynamic-plugins.yaml configuration file as follows:
    data:
    dynamic-plugins.yaml: |
    includes:
    - dynamic-plugins.default.yaml
    plugins:
    - package: oci://registry.access.redhat.com/rhdh/backstage-plugin-events-backend-module-github:<tag>
    disabled: false

    where:

    <tag>
    Enter your RHDH version and the plugin version, in the format <rhdh-version>--<plugin-version>. To find these versions, complete the following steps:
  2. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.10, use the format 1.10--<plugin-version>.
    Tip

    To ensure environment stability, use a SHA256 digest instead of a version tag. See Determining SHA256 Digests.

  3. To create HTTP endpoints to receive events for the github, add the following to your app-config.yaml file:
    events:
      http:
       topics:
        - github
      modules:
        github:
          webhookSecret: ${GITHUB_WEBHOOK_SECRET}
    Important

    Secure your workflow by adding a webhook secret token to validate webhook deliveries.

  4. Create a GitHub webhook with the following specifications:
    • For GitHub Discovery Events: push, repository
    • For GitHub Organizational Data Events: organization, team and membership
    • Content Type: application/json
    • Payload URL: https://<my_developer_hub_domain>/api/events/http/github Note

      Payload URL is the URL exposed after configuring the HTTP endpoint.

Results

  • Check the log for an entry that confirms that http endpoint was set up successfully to receive events from the GitHub webhook.
    Example of a log of successfully set up http endpoint
    {"level":"\u001b[32minfo\u001b[39m","message":"Registered /api/events/http/github to receive events","plugin":"events","service":"backstage","timestamp":"2025-11-03 02:19:12"}
  • For GitHub Discovery only:
    • Trigger a GitHub push event by adding, modifying or deleting the catalog-info.yaml file in the repository where you set up your webhook. A record of this event should appear in the pod logs of your RHDH instance.
      Example of a log with changes to catalog-info.yaml file
      {"level":"\u001b[32minfo\u001b[39m","message":"Processed Github push event: added 0 - removed 0 - modified 1","plugin":"catalog","service":"backstage","span_id":"47534b96c4afc654","target":"github-provider:providerId","timestamp":"2025-06-15 21:33:14","trace_flags":"01","trace_id":"ecc782deb86aed2027da0ae6b1999e5c"}
  • For GitHub Organizational Data only:
    • Newly added users and teams appear in the RHDH catalog.