Enable GitHub repository discovery

Configure automatic GitHub repository discovery to import repositories containing catalog-info.yaml files into the Red Hat Developer Hub catalog without manual registration.

Before you begin

Procedure

  1. Create a GitHub App to allow Developer Hub to access the GitHub API. Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens.
    1. Register a GitHub App with the following configuration:
      GitHub App name
      Enter a unique name identifying your GitHub App, such as integrating-with-rhdh-<GUID>.
      Homepage URL
      Enter your Developer Hub URL: https://<my_developer_hub_domain>.
      Authorization callback URL
      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/api/auth/github/handler/frame.
      Webhook
      Clear "Active", as this is not needed for authentication and catalog providers.
      App permissions

      Select permissions to define the level of access for the app. Adapt permissions to your needs:

      Reading software components
      Contents
      Read-only
      Commit statuses
      Read-only
      Reading organization data
      Members
      Read-only
      Publishing software templates

      Set permissions if you intend to use the same GitHub App for software templates.

      Administration
      Read & write (for creating repositories)
      Contents
      Read & write
      Metadata
      Read-only
      Pull requests
      Read & write
      Issues
      Read & write
      Workflows
      Read & write (if templates include GitHub workflows)
      Variables
      Read & write (if templates include GitHub Action Repository Variables)
      Secrets
      Read & write (if templates include GitHub Action Repository Secrets)
      Environments
      Read & write (if templates include GitHub Environments)
      Organization permissions
      Members
      Read-only
      Where can this GitHub App be installed?
      Select Only on this account.
    2. In the General Clients secrets section, click Generate a new client secret.
    3. In the General Private keys section, click Generate a private key.
    4. In the Install App tab, choose an account to install your GitHub App on.
    5. Save the following values for the next step:
  2. App ID
  3. Client ID
  4. Client secret
  5. Private key
  6. Add your GitHub credentials to Developer Hub by adding the following key/value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using the corresponding environment variable name for each secret.
    GITHUB_APP_APP_ID
    Enter the saved App ID.
    GITHUB_APP_CLIENT_ID_INTEGRATION
    Enter the saved Client ID.
    GITHUB_APP_CLIENT_SECRET_INTEGRATION
    Enter the saved Client Secret.
    GITHUB_APP_PRIVATE_KEY
    Enter the saved Private key.
    GITHUB_HOST
    Enter the GitHub hostname without a scheme, such as github.com. The integrations.github host expects a hostname only; a URL such as https://github.com fails integration validation.
    GITHUB_ORG
    Enter your GitHub organization name, such as <your_github_organization_name>.
  7. Enable the plugin-catalog-backend-module-github plugin in your dynamic-plugins.yaml file.

    This plugin discovers catalog entities by scanning repositories within a GitHub organization for catalog-info.yaml files. It provides an automated alternative to manually registering components via catalog.locations. When a repository contains a catalog-info.yaml file, the entity is ingested into the catalog as a component.

    dynamic-plugins.yaml file fragment

    plugins:
      - package: ref://backstage-plugin-catalog-backend-module-github
        enabled: true
  8. Configure the GitHub integration, by adding the catalog.providers.github and the integrations.github sections to your custom Developer Hub app-config.yaml configuration file:

    app-config.yaml file fragment with mandatory fields to enable GitHub integration

    catalog:
      providers:
        github:
          providerId:
            organization: "${GITHUB_ORG}"
            schedule:
              frequency:
                minutes: 30
              initialDelay:
                seconds: 15
              timeout:
                minutes: 15
    integrations:
      github:
        - host: "${GITHUB_HOST}"
          apps:
            - appId: ${GITHUB_APP_APP_ID}
              clientId: ${GITHUB_APP_CLIENT_ID_INTEGRATION}
              clientSecret: ${GITHUB_APP_CLIENT_SECRET_INTEGRATION}
              privateKey: |
                ${GITHUB_APP_PRIVATE_KEY}