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
- You have added a custom Developer Hub application configuration.
- You have sufficient permissions in GitHub to create and manage a GitHub App.
- To allow users to access GitHub templates or plugins that require GitHub authentication, you have configured GitHub either as an auxiliary authentication provider or as your main authentication provider.
Procedure
-
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.
-
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.
-
In the General
Clients secrets section, click Generate a new client secret. -
In the General
Private keys section, click Generate a private key. - In the Install App tab, choose an account to install your GitHub App on.
- Save the following values for the next step:
-
Register a GitHub App with the following configuration:
- App ID
- Client ID
- Client secret
- Private key
-
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. Theintegrations.githubhost expects a hostname only; a URL such ashttps://github.comfails integration validation. -
GITHUB_ORG - Enter your GitHub organization name, such as
<your_github_organization_name>.
-
-
Enable the
plugin-catalog-backend-module-githubplugin in yourdynamic-plugins.yamlfile.This plugin discovers catalog entities by scanning repositories within a GitHub organization for
catalog-info.yamlfiles. It provides an automated alternative to manually registering components viacatalog.locations. When a repository contains acatalog-info.yamlfile, the entity is ingested into the catalog as a component.dynamic-plugins.yamlfile fragmentplugins: - package: ref://backstage-plugin-catalog-backend-module-github enabled: true -
Configure the GitHub integration, by adding the
catalog.providers.githuband theintegrations.githubsections to your custom Developer Hubapp-config.yamlconfiguration file:app-config.yamlfile fragment with mandatory fields to enable GitHub integrationcatalog: 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}