Getting started with Red Hat Developer Hub

Procedure

1. In the Red Hat OpenShift cluster, navigate to the main page of the GitHub organization where you want to create the OAuth application.
2. Click Settings → Developer Settings → OAuth Apps → Register an application
3. Enter the application name as Developer Hub.

4. Add the following URL as the Homepage URL:

   https://developer-hub-<NAMESPACE_NAME>.<OPENSHIFT_ROUTE_HOST>/

5. Add the following URL as Authorization callback URL:

   https://developer-hub-<NAMESPACE_NAME>.<OPENSHIFT_ROUTE_HOST>/api/auth/github/handler/frame

6. Clear the Enable Device Flow checkbox.
7. Click Register application to create your OAuth application.
8. After creating the application, click Generate a new client secret and copy the generated client secret.
9. In OpenShift, click ConfigMaps.

10. Generate a key/value secret named 'github-secrets' using the provided environment variables as keys, and input the values you generated for your GitHub OAuth application:

    1. In Red Hat OpenShift, go to the Secrets tab and click Create.
    2. Select Key/value secret.
    3. Enter Secret name as github-secrets.

    4. Add environment variables as Key and Value and click Create.

       Table 3.1. Environment variables

       Key	Value
       GITHUB_OAUTH_CLIENT_ID	Client ID from OAuth application
       GITHUB_OAUTH_CLIENT_SECRET	Client Secret from OAuth application

11. Modify your app-config-rhdh ConfigMap to include the GitHub authentication configuration as follows:

    kind: ConfigMap
    apiVersion: v1
    metadata:
      name: app-config-rhdh
    data:
      app-config-rhdh.yaml: |
        app:
          title: Red Hat Developer Hub
        auth:
          # see https://backstage.io/docs/auth/ to learn about auth providers
          environment: development
          providers:
            github:
              development:
                clientId: ${GITHUB_OAUTH_CLIENT_ID}
                clientSecret: ${GITHUB_OAUTH_CLIENT_SECRET}

12. Click Save.
13. Navigate to the Helm tab and select Upgrade.

14. Use one of the following views to edit the Helm configuration:

    • Using Form view

      1. Expand Root Schema → Backstage Chart Schema → Backstage Parameters → Backstage container environment variables from existing Secrets.
      2. Click the Add Backstage container environment variables from existing Secrets link.
      3. Enter github-secrets as the value.
      4. Click Upgrade.

    • Using YAML view

      1. Set the value of the upstream.backstage.extraEnvVarsSecrets parameter to github-secrets as shown in the following example:

         # other Red Hat Developer Hub Helm Chart configurations
         upstream:
           backstage:
             # other Red Hat Developer Hub Helm Chart configurations
             extraEnvVarsSecrets:
               - github-secrets
             # other Red Hat Developer Hub Helm Chart configurations

      2. Click Upgrade.

Procedure

1. In the Red Hat OpenShift cluster, navigate to the main page of the GitHub organization where you want to create the OAuth application.
2. Click Settings → Developer Settings → GitHub Apps → New GitHub App.
3. Enter the application name as Developer Hub.

4. Add the following URL as the Homepage URL:

   https://developer-hub-<NAMESPACE_NAME>.<OPENSHIFT_ROUTE_HOST>/

5. Add the following URL as Authorization callback URL:

   https://developer-hub-<NAMESPACE_NAME>.<OPENSHIFT_ROUTE_HOST>/api/auth/github/handler/frame

6. Deselect Webhook URL → Active.
7. Under the Where can this GitHub App be installed? section, ensure that Only on this account is selected.
8. Click Register application.
9. After creating the application, click Generate a new client secret and copy the generated client secret.
10. Click Generate a private key at the bottom of the page and download the generated file.
11. In OpenShift, click ConfigMaps.

12. Generate a key/value secret named 'github-secrets' using the provided environment variables as keys, and input the values you generated for your GitHub OAuth application:

    1. In Red Hat OpenShift, go to the Secrets tab and click Create.
    2. Select Key/value secret.
    3. Enter Secret name as github-secrets.
    4. Add environment variables as Key and Value and click Create.

    Table 3.2. Environment variables

    Key	Value
    GITHUB_APP_APP_ID	App ID from GitHub application
    GITHUB_APP_CLIENT_ID	Client ID from GitHub application
    GITHUB_APP_CLIENT_SECRET	Client Secret from GitHub application
    GITHUB_APP_WEBHOOK_URL	Enter "none"
    GITHUB_APP_WEBHOOK_SECRET	Enter "none"
    GITHUB_APP_PRIVATE_KEY	Upload the private key that was downloaded

13. Modify your app-config-rhdh ConfigMap to include the GitHub integration configuration as follows:

    kind: ConfigMap
    apiVersion: v1
    metadata:
      name: app-config-rhdh
    data:
      app-config-rhdh.yaml: |
        app:
          title: Red Hat Developer Hub
        integrations:
          github:
            - host: github.com
              apps:
                - appId: ${GITHUB_APP_APP_ID}
                  clientId: ${GITHUB_APP_CLIENT_ID}
                  clientSecret: ${GITHUB_APP_CLIENT_SECRET}
                  webhookUrl: ${GITHUB_APP_WEBHOOK_URL}
                  webhookSecret: ${GITHUB_APP_WEBHOOK_SECRET}
                  privateKey: |
                    ${GITHUB_APP_PRIVATE_KEY}

14. Click Toplogy → developer hub → Actions (drop-down) → Restart rollout.

Procedure

1. In the Developer perspective of the OpenShift Container Platform web console, go to the Helm tab.
2. Click the overflow menu on a Helm release and select Upgrade.

3. Use one of the following views to edit the Helm configuration:

   • Using Form view

     1. Expand Root Schema → global → Dynamic plugins configuration → List of dynamic plugins that should be installed in the backstage application.
     2. Click the Add List of dynamic plugins that should be installed in the backstage application link.

     3. In the Package specification of the dynamic plugin to install. It should be usable by the npm pack command. field, add the following value:

        ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic

        
     4. Click Upgrade.

   • Using YAML view

     1. Set the value of the global.dynamic.plugins.package parameter to ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic as shown in the following example:

        global:
          dynamic:
            # other Red Hat Developer Hub Helm Chart configurations
            plugins:
              - disabled: false
                package: >-
                  ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic
            # other Red Hat Developer Hub Helm Chart configurations

     2. Click Upgrade.

4. Add the following code in the ConfigMap:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: app-config-rhdh
   data:
     app-config-rhdh.yaml: |
       ...
         catalog:
           providers:
             github:
               providerId:
                 organization: '${GITHUB_ORG}'
                 schedule:
                   frequency:
                     minutes: 30
                   initialDelay:
                     seconds: 15
                   timeout:
                     minutes: 3
       ...

   In the previous code, replace ${GITHUB_ORG} with the GitHub organization from where you want to discover the components. Also, if there is a single provider, then following code can be added in the ConfigMap:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: app-config-rhdh
   data:
     app-config-rhdh.yaml: |
       ...
       catalog:
         providers:
           github:
             organization: ${GITHUB_ORG}
             schedule:
               frequency: { minutes: 1 }
               timeout: { minutes: 1 }
               initialDelay: { seconds: 100 }
       ...

   The providerId in the previous code is required to identify the provider when there is a list of them.

5. Click Save.

Procedure

1. In the Developer perspective of the OpenShift Container Platform web console, go to the Helm tab.
2. Click the overflow menu on a Helm release and select Upgrade.

3. Use one of the following views to edit the Helm configuration:

   • Using Form view

     1. Expand Root Schema → global → Dynamic plugins configuration → List of dynamic plugins that should be installed in the backstage application.
     2. Click the Add List of dynamic plugins that should be installed in the backstage application link.

     3. In the Package specification of the dynamic plugin to install. It should be usable by the npm pack command. field, add the following value:

        ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic

        
     4. Click Upgrade.

   • Using YAML view

     1. Set the value of the global.dynamic.plugins.package parameter to ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic as shown in the following example:

        global:
          dynamic:
            # other Red Hat Developer Hub Helm Chart configurations
            plugins:
              - disabled: false
                package: >-
                  ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic
            # other Red Hat Developer Hub Helm Chart configurations

     2. Click Upgrade.

4. Add the following code in the ConfigMap:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: app-config-rhdh
   data:
     app-config-rhdh.yaml: |
       ...
       catalog:
         providers:
           githubOrg:
             id: production
             githubUrl: "${GITHUB_URL}"
             orgs: [ "${GITHUB_ORG}" ]
       ...

   where:

   ${GITHUB_URL}

   Denotes a variable that you must replace with the GitHub URL.

   ${GITHUB_ORG}

   Denotes a variable that you must replace with the GitHub organization you want to ingest users from.

5. Click Save.