Configure the GitLab Events Module plugin

Configure GitLab webhooks and system hooks to trigger real-time updates for GitLab Discovery and organizational data.

Before you begin

  • You have added your GitLab integration credentials in the app-config.yaml file.

    For self-hosted GitLab instances:

    integrations:
      gitlab:
        - host: ${GITLAB_HOST}
          token: ${GITLAB_TOKEN}
          apiBaseUrl: https://${GITLAB_HOST}/api/v4

    For GitLab.com:

    integrations:
      gitlab:
        - host: gitlab.com
          token: ${GITLAB_TOKEN}
  • You have defined the schedule.frequency in the app-config.yaml file as a longer time period, such as 24 hours.
  • For GitLab Discovery only: You have enabled GitLab Discovery by adding the catalog-backend-module-gitlab plugin with the following configuration in the app-config.yaml file:
    catalog:
      providers:
        gitlab:
          default:
            host: ${GITLAB_HOST}
            group: ${GITLAB_ORG}
            schedule:
              initialDelay:
                seconds: 15
              frequency:
                hours: 24
              timeout:
                minutes: 3
  • For GitLab Organizational Data only: You have enabled GitLab Authentication with user ingestion.

About this task

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

Important

These features are for Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information on Red Hat Technology Preview features, see Technology Preview Features Scope.

Procedure

  1. Add the GitLab 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-gitlab:<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.
  3. To create HTTP endpoints to receive events for gitlab, add the following to your app-config.yaml file:
    events:
      http:
        topics:
          - gitlab
      modules:
        gitlab:
          webhookSecret: ${GITLAB_WEBHOOK_SECRET}
    Important

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

  4. For GitLab Discovery, create a GitLab webhook at the group or project level with the following specifications:
    • Trigger: push events
    • Payload URL: https://<my_developer_hub_domain>/api/events/http/gitlab Note

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

  5. For GitLab Organizational Data, create a GitLab system hook with the following specifications:
    • Triggers: group_create, group_destroy, group_rename, user_create, user_destroy, user_add_to_group, user_remove_from_group events
    • URL: https://<my_developer_hub_domain>/api/events/http/gitlab

Results

  • Check the log for an entry that confirms that the http endpoint was set up successfully to receive events from the GitLab webhook.
    Example of a log of successfully set up http endpoint
    {"level":"\u001b[32minfo\u001b[39m","message":"Registered /api/events/http/gitlab to receive events","plugin":"events","service":"backstage","timestamp":"2025-11-03 02:19:12"}
  • For GitLab Discovery only:
    • Trigger a GitLab 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 GitLab push event from https://gitlab.com/backstage-test-catalog/test-repo-1: added 1 - removed 0 - modified 0","plugin":"catalog","service":"backstage","span_id":"abfe425c441ee3e8","target":"GitlabDiscoveryEntityProvider:providerId","timestamp":"2025-09-07 23:03:12","trace_flags":"01","trace_id":"0c21b7c71d7ce8aa626d42e6f4060716"}
  • For GitLab Organizational Data only:
    • Newly added users and groups appear in the RHDH catalog.