Procedure

1. Open your Helm chart values.yaml file for editing.

2. Add the global.catalogIndex.extraImages parameter with entries for each extra catalog index image you want to configure:

   global:
     catalogIndex:
       extraImages:
         - name: community
           registry: quay.io
           repository: community/rhdh-plugin-catalog
           tag: v1.10.0
         - registry: registry.example.com
           repository: internal/custom-plugins
           tag: latest

   Where:

   name (optional)

   The subdirectory name under /extensions/extra/ where catalog entities are extracted. If omitted, Red Hat Developer Hub auto-derives the name from the image reference.

   registry (required)

   The container registry hostname.

   repository (required)

   The repository path within the registry.

   tag (required)

   The image tag.

3. Deploy or upgrade the Helm chart:

   $ helm upgrade my-rhdh redhat-developer/backstage \
       --install \
       --values values.yaml \
       --namespace {my-product-namespace}

Verification

1. Wait for the Red Hat Developer Hub deployment to complete and all pods to reach the Running state:

   $ kubectl get pods -n {my-product-namespace}

2. Verify that the extra catalog entities were extracted by inspecting the install-dynamic-plugins init container logs:

   $ kubectl logs -n {my-product-namespace} \
       <pod_name> \
       -c install-dynamic-plugins

   Replace <pod_name> with the name of your Red Hat Developer Hub pod. Look for log messages indicating extraction of extra catalog index images.

3. Verify the subdirectory structure by executing a shell in the Red Hat Developer Hub container:

   $ kubectl exec -n {my-product-namespace} <pod_name> -- ls -l /extensions/extra/

   You should see subdirectories corresponding to the name values or auto-derived names from your extraImages configuration.

4. Verify that plugins from the extra catalogs appear in the Extensions UI:

   1. Navigate to your Red Hat Developer Hub instance in a web browser.
   2. Open the Extensions UI.
   3. Look for plugins organized under subdirectories matching your extra catalog names.

Procedure

1. Open your Backstage custom resource YAML file for editing.

2. Add an extraEnvs section targeting the install-dynamic-plugins container with the EXTRA_CATALOG_INDEX_IMAGES environment variable:

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: {product-custom-resource-type}
   metadata:
     name: {my-product-cr-name}
   spec:
     application:
       extraEnvs:
         envs:
           - name: EXTRA_CATALOG_INDEX_IMAGES
             value: "community=quay.io/community/rhdh-plugin-catalog:v1.10.0,registry.example.com/internal/custom-plugins:latest"
         container: install-dynamic-plugins

   In this example:

3. The first entry uses the name=image_ref format with an explicit subdirectory name (community).
4. The second entry uses the plain image_ref format, so Red Hat Developer Hub auto-derives the subdirectory name from the image reference.

5. Format the EXTRA_CATALOG_INDEX_IMAGES value as a comma-separated list of catalog index images. Each entry can use one of two formats:

   Explicit name format

   <name>=<image_ref>

   Example: community=quay.io/community/plugins:v1.10

   Use this format when you want a readable, stable subdirectory name.

   Plain image reference format

   <image_ref>

   Example: quay.io/community/plugins:v1.10

   Use this format when subdirectory name readability is not critical. Red Hat Developer Hub auto-derives the subdirectory name by replacing /, :, and @ characters with underscores (_).

6. Apply the Backstage custom resource:

   $ oc apply -f backstage-cr.yaml -n {my-product-namespace}

Verification

1. Wait for the Red Hat Developer Hub deployment to complete and the pod to reach the Running state:

   $ oc get pods -n {my-product-namespace}

2. Verify that the extra catalog entities were extracted by inspecting the install-dynamic-plugins init container logs:

   $ oc logs -n {my-product-namespace} \
       <pod_name> \
       -c install-dynamic-plugins

   Replace <pod_name> with the name of your Red Hat Developer Hub pod. Look for log messages indicating extraction of extra catalog index images.

   If you configured duplicate subdirectory names, check for warning messages in the logs.

3. Verify the subdirectory structure by executing a shell in the Red Hat Developer Hub container:

   $ oc exec -n {my-product-namespace} <pod_name> -- ls -l /extensions/extra/

   You should see subdirectories corresponding to the explicit names or auto-derived names from your EXTRA_CATALOG_INDEX_IMAGES configuration.

4. Verify that plugins from the extra catalogs appear in the Extensions UI:

   1. Navigate to your Red Hat Developer Hub instance in a web browser.
   2. Open the Extensions UI.
   3. Look for plugins organized under subdirectories matching your extra catalog names.

Procedure

1. Mirror each extra catalog index image to your internal registry.

   $ skopeo copy \
       docker://quay.io/community/rhdh-plugin-catalog:v1.10.0 \
       docker://internal-registry.example.com/community/rhdh-plugin-catalog:v1.10.0

   Repeat this step for each extra catalog index image you want to configure.

2. Edit the Red Hat Developer Hub Operator deployment to add RELATED_IMAGE_extra_catalog_index_<name> environment variables for each extra catalog index image. The <name> portion must match the subdirectory name you will use in the EXTRA_CATALOG_INDEX_IMAGES configuration:

   $ oc edit deployment rhdh-operator -n <operator_namespace>

   Replace <operator_namespace> with the namespace where the Red Hat Developer Hub Operator is deployed.

3. In the Operator deployment, add environment variables to the manager container under spec.template.spec.containers:

   spec:
     template:
       spec:
         containers:
           - name: manager
             env:
               - name: RELATED_IMAGE_extra_catalog_index_community
                 value: internal-registry.example.com/community/rhdh-plugin-catalog:v1.10.0
               - name: RELATED_IMAGE_extra_catalog_index_partner
                 value: internal-registry.example.com/partner/plugin-catalog:v1.0.0

   In this example:

4. The RELATED_IMAGE_extra_catalog_index_community variable points to the mirrored community catalog image.
5. The RELATED_IMAGE_extra_catalog_index_partner variable points to the mirrored partner catalog image.
6. The suffixes community and partner must match the names used in the EXTRA_CATALOG_INDEX_IMAGES configuration in the next step.

7. Edit your Backstage custom resource to add the EXTRA_CATALOG_INDEX_IMAGES environment variable. Use the same subdirectory names (community, partner) that you used in the RELATED_IMAGE variable names:

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: {product-custom-resource-type}
   metadata:
     name: {my-product-cr-name}
   spec:
     application:
       extraEnvs:
         envs:
           - name: EXTRA_CATALOG_INDEX_IMAGES
             value: "community=internal-registry.example.com/community/rhdh-plugin-catalog:v1.10.0,partner=internal-registry.example.com/partner/plugin-catalog:v1.0.0"
         container: install-dynamic-plugins

   Important

   The subdirectory names in the name=image_ref entries (community, partner) must match the suffixes in the corresponding RELATED_IMAGE_extra_catalog_index_<name> environment variables. If the names do not match, catalog extraction fails.

8. Apply the Backstage custom resource:

   $ oc apply -f backstage-cr.yaml -n {my-product-namespace}

Verification

1. Wait for the Red Hat Developer Hub deployment to complete and the pod to reach the Running state:

   $ oc get pods -n {my-product-namespace}

2. Verify that the extra catalog entities were extracted by inspecting the install-dynamic-plugins init container logs:

   $ oc logs -n {my-product-namespace} \
       <pod_name> \
       -c install-dynamic-plugins

   Replace <pod_name> with the name of your Red Hat Developer Hub pod. Look for log messages indicating successful extraction of extra catalog index images.

3. Verify the subdirectory structure:

   $ oc exec -n {my-product-namespace} <pod_name> -- ls -l /extensions/extra/

   You should see subdirectories corresponding to the names used in your EXTRA_CATALOG_INDEX_IMAGES configuration (community, partner).

4. Verify that plugins from the extra catalogs appear in the Extensions UI:

   1. Navigate to your Red Hat Developer Hub instance in a web browser.
   2. Open the Extensions UI.
   3. Look for plugins organized under subdirectories matching your extra catalog names.

1. Verify that the RELATED_IMAGE_extra_catalog_index_<name> variable names match the subdirectory names in EXTRA_CATALOG_INDEX_IMAGES.
2. Check that the mirrored images are accessible from the Red Hat Developer Hub pod’s network.
3. Inspect the install-dynamic-plugins init container logs for error messages related to image pull failures or name mismatches.

Procedure

1. Locate the Red Hat Developer Hub Local .env file. By default, this file is in the Red Hat Developer Hub Local installation directory.
2. Open the .env file for editing.

3. Add or edit the EXTRA_CATALOG_INDEX_IMAGES environment variable with a comma-separated list of catalog index images:

   EXTRA_CATALOG_INDEX_IMAGES="community=quay.io/community/rhdh-plugin-catalog:v1.10.0,quay.io/partner/plugin-catalog:v1.0.0,internal=localhost:5000/custom-plugins:latest"

   In this example:

4. The first entry uses the name=image_ref format with an explicit subdirectory name (community).
5. The second entry uses the plain image_ref format, so Red Hat Developer Hub Local auto-derives the subdirectory name from the image reference: quay.io_partner_plugin-catalog_v1.0.0.
6. The third entry references a locally-hosted registry on localhost:5000 with the explicit name internal.
7. Save the .env file.

8. Restart Red Hat Developer Hub Local to apply the configuration:

   $ rhdh-local restart

   Or, if you use Podman Compose directly:

   $ podman-compose down
   $ podman-compose up -d

Verification

1. Wait for the Red Hat Developer Hub Local containers to start and reach a healthy state:

   $ podman ps

2. Verify that the extra catalog entities were extracted by checking the /extensions/extra/ directory structure:

   $ podman exec <container_name> ls -l /extensions/extra/

   Replace <container_name> with the name of your Red Hat Developer Hub Local container. You should see subdirectories corresponding to the explicit names or auto-derived names from your EXTRA_CATALOG_INDEX_IMAGES configuration.

3. Verify that plugins from the extra catalogs appear in the Extensions UI:

   1. Navigate to your local Red Hat Developer Hub instance in a web browser (typically http://localhost:7007).
   2. Open the Extensions UI.
   3. Look for plugins organized under subdirectories matching your extra catalog names.

Procedure

1. Add Argo CD instance information to your app-config.yaml configmap as shown in the following example:

   argocd:
     appLocatorMethods:
       - type: 'config'
         instances:
           - name: argoInstance1
             url: https://argoInstance1.com
             username: ${ARGOCD_USERNAME}
             password: ${ARGOCD_PASSWORD}
           - name: argoInstance2
             url: https://argoInstance2.com
             username: ${ARGOCD_USERNAME}
             password: ${ARGOCD_PASSWORD}

   Note

   Avoid using a trailing slash in the url, as it might cause unexpected behavior.

2. Add the following annotation to the entity's catalog-info.yaml file to identify the Argo CD applications.

   annotations:
     ...
     # The label that Argo CD uses to fetch all the applications. The format to be used is label.key=label.value. For example, rht-gitops.com/janus-argocd=quarkus-app.
   
     argocd/app-selector: '${ARGOCD_LABEL_SELECTOR}'

3. (Optional) Add the following annotation to the entity's catalog-info.yaml file to switch between Argo CD instances as shown in the following example:

    annotations:
      ...
       # The Argo CD instance name used in `app-config.yaml`.
   
       argocd/instance-name: '${ARGOCD_INSTANCE}'

   Note

   If you do not set this annotation, the Argo CD plugin defaults to the first Argo CD instance configured in app-config.yaml.

4. To enable the Argo CD plugin, set the disabled property to false in your dynamic-plugins.yaml file as follows:

   Important

   Argo CD contains multiple plugin options you can choose from for your Argo CD configuration:

   • Community Argo CD:

     • @backstage-community/plugin-argocd
     • @backstage-community/plugin-argocd-backend

   • Roadie Argo CD:

     • @roadiehq/backstage-plugin-argo-cd
     • @roadiehq/backstage-plugin-argo-cd-backend

   Community and Roadie plugins are comparable in functionality but have different features. For example, both versions feature scaffolder actions, however, their implementation is different: the Community version contains scaffolder actions by default, the Roadie version requires an additional plugin.

   The recommended combination is to use @backstage-community/plugin-argocd together with @backstage-community/plugin-argocd-backend.

   However, you can also combine @roadiehq/backstage-plugin-argo-cd together with @roadiehq/backstage-plugin-argo-cd-backend.

   Mixing Community and Roadie plugins is not recommended.

   plugins:
     - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/roadiehq-backstage-plugin-argo-cd-backend:<tag>
       disabled: false
     - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-argocd:<tag>
       disabled: false

   where:

   <tag>

   Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

   1. Find your Backstage version in the RHDH release notes preface.

   2. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.9 based on Backstage 1.45.3, use the format bs_1.45.3__<plugin-version>.

      Tip

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

Procedure

1. In the app-config.yaml file in your Developer Hub instance, add the following customResources component under the kubernetes configuration to enable Argo Rollouts and Analysis Runs:

   kubernetes:
     ...
     customResources:
       - group: 'argoproj.io'
         apiVersion: 'v1alpha1'
         plural: 'Rollouts'
       - group: 'argoproj.io'
         apiVersion: 'v1alpha1'
         plural: 'analysisruns'

2. Grant ClusterRole permissions for custom resources.

   Note

   1. If the Developer Hub Kubernetes plugin is already configured, the ClusterRole permissions for Rollouts and AnalysisRuns might already be granted.
   2. Use the prepared manifest to give read-only ClusterRole access to both the Kubernetes and ArgoCD plugins.
   1. If the ClusterRole permission is not granted, use the following YAML manifest to create the ClusterRole:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: backstage-read-only
   rules:
     - apiGroups:
         - argoproj.io
       resources:
         - rollouts
         - analysisruns
       verbs:
         - get
         - list

   1. Apply the manifest to the cluster using kubectl:

      $ kubectl apply -f <your_cluster_role_file>.yaml

   2. Ensure the ServiceAccount accessing the cluster has this ClusterRole assigned.

3. Add annotations to catalog-info.yaml to identify Kubernetes resources for Backstage.

   1. For identifying resources by entity ID:

      annotations:
        ...
        backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

   2. (Optional) For identifying resources by namespace:

      annotations:
        ...
        backstage.io/kubernetes-namespace: <RESOURCE_NAMESPACE>

   3. For using custom label selectors, which override resource identification by entity ID or namespace:

      annotations:
        ...
        backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end'

      Note

      Ensure you specify the labels declared in backstage.io/kubernetes-label-selector on your Kubernetes resources. This annotation overrides entity-based or namespace-based identification annotations, such as backstage.io/kubernetes-id and backstage.io/kubernetes-namespace.

4. Add label to Kubernetes resources to enable Developer Hub to find the appropriate Kubernetes resources.

   1. Developer Hub Kubernetes plugin label: Add this label to map resources to specific Developer Hub entities.

      labels:
        ...
        backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

   2. GitOps application mapping: Add this label to map Argo CD Rollouts to a specific GitOps application

      labels:
        ...
        app.kubernetes.io/instance: <GITOPS_APPLICATION_NAME>

   Note

   If using the label selector annotation (backstage.io/kubernetes-label-selector), ensure the specified labels are present on the resources. The label selector will override other annotations such as kubernetes-id or kubernetes-namespace.

Verification

1. Push the updated configuration to your GitOps repository to trigger a rollout.
2. Open Red Hat Developer Hub interface and navigate to the entity you configured.
3. Select the CD tab and then select the GitOps application. The side panel opens.

4. In the Resources table of the side panel, verify that the following resources are displayed:

   • Rollouts
   • Analysis Runs (optional)

5. Expand a rollout resource and review the following details:

   • The Revisions row displays traffic distribution details for different rollout versions.
   • The Analysis Runs row displays the status of analysis tasks that evaluate rollout success.

Procedure

1. Set the proxy to the required JFrog Artifactory server in the app-config.yaml file as follows:

   proxy:
     endpoints:
       '/jfrog-artifactory/api':
         target: http://<hostname>:8082 # or https://<customer>.jfrog.io
         headers:
         # Authorization: 'Bearer <YOUR TOKEN>'
         # Change to "false" in case of using a self-hosted Artifactory instance with a self-signed certificate
         secure: true

2. Add the following annotation to the entity’s catalog-info.yaml file to enable the JFrog Artifactory plugin features in RHDH components:

   metadata:
       annotations:
         'jfrog-artifactory/image-name': '<IMAGE-NAME>'

Procedure

1. To configure the Keycloak plugin, add the following in your app-config.yaml file:

   schedule

   Configure the schedule frequency, timeout, and initial delay. The fields support cron, ISO duration, "human duration" as used in code.

        catalog:
          providers:
            keycloakOrg:
              default:
                schedule:
                  frequency: { minutes: 1 }
                  timeout: { minutes: 1 }
                  initialDelay: { seconds: 15 }

   userQuerySize and groupQuerySize

   Optionally, configure the Keycloak query parameters to define the number of users and groups to query at a time. Default values are 100 for both fields.

      catalog:
        providers:
          keycloakOrg:
            default:
              userQuerySize: 100
              groupQuerySize: 100

   Authentication

   Communication between Developer Hub and Keycloak is enabled by using the Keycloak API. Username and password, or client credentials are supported authentication methods.

   The following table describes the parameters that you can configure to enable the plugin under catalog.providers.keycloakOrg.<ENVIRONMENT_NAME> object in the app-config.yaml file:

   Name	Description	Default Value	Required
   baseUrl	Location of the Keycloak server, such as https://localhost:8443/auth.	""	Yes
   realm	Realm to synchronize	master	No
   loginRealm	Realm used to authenticate	master	No
   username	Username to authenticate	""	Yes if using password based authentication
   password	Password to authenticate	""	Yes if using password based authentication
   clientId	Client ID to authenticate	""	Yes if using client credentials based authentication
   clientSecret	Client Secret to authenticate	""	Yes if using client credentials based authentication
   userQuerySize	Number of users to query at a time	100	No
   groupQuerySize	Number of groups to query at a time	100	No

2. When using client credentials

   1. Set the access type to confidential.
   2. Enable service accounts.
   3. Add the following roles from the realm-management client role:
3. query-groups
4. query-users
5. view-users

6. Optionally, if you have self-signed or corporate certificate issues, you can set the following environment variable before starting Developer Hub:

   NODE_TLS_REJECT_UNAUTHORIZED=0

   Warning

   Setting the environment variable is not recommended.

Procedure

1. Set the proxy to the required Nexus Repository Manager server in the app-config.yaml file as follows:

   proxy:
       '/nexus-repository-manager':
       target: 'https://<NEXUS_REPOSITORY_MANAGER_URL>'
       headers:
           X-Requested-With: 'XMLHttpRequest'
           # Uncomment the following line to access a private Nexus Repository Manager using a token
           # Authorization: 'Bearer <YOUR TOKEN>'
       changeOrigin: true
       # Change to "false" in case of using self hosted Nexus Repository Manager instance with a self-signed certificate
       secure: true

2. Optional: Change the base URL of Nexus Repository Manager proxy as follows:

   nexusRepositoryManager:
       # default path is `/nexus-repository-manager`
       proxyPath: /custom-path

3. Optional: Enable the following experimental annotations:

   nexusRepositoryManager:
       experimentalAnnotations: true

4. Annotate your entity using the following annotations:

   metadata:
       annotations:
       # insert the chosen annotations here
       # example
       nexus-repository-manager/docker.image-name: `<ORGANIZATION>/<REPOSITORY>`,

Procedure

1. The Bulk Import plugins are installed but disabled by default. To enable the ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic and ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import plugins, edit your dynamic-plugins.yaml with the following content:

   plugins:
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic
       disabled: false
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
       disabled: false

   See Installing and viewing plugins in Red Hat Developer Hub.

2. Configure the required bulk.import RBAC permission for the users who are not administrators as shown in the following code:

   rbac-policy.csv fragment

   p, role:default/bulk-import, bulk.import, use, allow
   g, user:default/<your_user>, role:default/bulk-import

   Note that only Developer Hub administrators or users with the bulk.import permission can use the Bulk Import feature. See Permission policies in Red Hat Developer Hub.

Verification

1. The sidebar displays a Bulk Import option.
2. The Bulk Import page shows a list of added GitHub repositories and GitLab projects.

Procedure

1. Click Bulk Import in the Developer Hub left sidebar.

2. If your RHDH instance has multiple source control tools configured, select GitHub from the Source control tool list.

   The interface displays GitHub repositories that your authenticated user account can access, excluding repositories already present in the catalog.

3. Select the repositories to import, and click Add.

   Developer Hub creates a pull request in each selected repository to add the required catalog-info.yaml file using your GitHub credentials.

4. For each repository to import, click PR to review and merge the changes in GitHub.

Verification

1. Click Bulk Import in the Developer Hub left sidebar.
2. Verify that each imported GitHub repository in the Selected repositories list has the status Waiting for approval or Imported.

3. For each Waiting for approval repository, click the pull request link to review and merge the catalog-info.yaml file in the corresponding repository.

   The pull request is created using your GitHub user account, ensuring proper attribution in the repository history.

Procedure

1. In the Developer Hub left sidebar, click Bulk Import.

2. If your RHDH instance has multiple source control tools configured, select GitLab from the Source control tool list.

   The interface displays GitLab projects that your authenticated user account can access, excluding projects already present in the catalog.

3. Select the projects to import, and click Add.

   Developer Hub creates a merge request in each selected project to add the required catalog-info.yaml file using your GitLab credentials.

4. For each project to import, click MR to review and merge the changes in GitLab.

Verification

1. Click Bulk Import in the Developer Hub left sidebar.
2. Verify that each imported GitLab project in the Selected projects list has the status Waiting for approval or Imported.

3. For projects with the Waiting for approval status, click the merge request link to review and add the catalog-info.yaml file to the project repository.

   The merge request is created using your GitLab user account, ensuring proper attribution in the project history.

Procedure

1. Access your Developer Hub backend logs where audit log events are recorded.

2. Review the following Bulk Import audit log events to monitor repository operations:

   BulkImportUnknownEndpoint

   Tracks requests to unknown endpoints.

   BulkImportPing

   Tracks GET requests to the /ping endpoint, which allows us to make sure the bulk import backend is up and running.

   BulkImportFindAllOrganizations

   Tracks GET requests to the /organizations endpoint, which returns the list of organizations accessible from all configured GitHub Integrations.

   BulkImportFindRepositoriesByOrganization

   Tracks GET requests to the /organizations/:orgName/repositories endpoint, which returns the list of repositories for the specified organization (accessible from any of the configured GitHub Integrations).

   BulkImportFindAllRepositories

   Tracks GET requests to the /repositories endpoint, which returns the list of repositories accessible from all configured GitHub Integrations.

   BulkImportFindAllImports

   Tracks GET requests to the /imports endpoint, which returns the list of existing import jobs along with their statuses.

   BulkImportCreateImportJobs

   Tracks POST requests to the /imports endpoint, which allows to submit requests to bulk-import one or many repositories into the Developer Hub catalog, by eventually creating import pull requests in the target repositories.

   BulkImportFindImportStatusByRepo

   Tracks GET requests to the /import/by-repo endpoint, which fetches details about the import job for the specified repository.

   BulkImportDeleteImportByRepo

   Tracks DELETE requests to the /import/by-repo endpoint, which deletes any existing import job for the specified repository, by closing any open import pull request that could have been created.

   Example audit log output:

   {
     "actor": {
       "actorId": "user:default/myuser",
       "hostname": "localhost",
       "ip": "::1",
       "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
     },
     "eventName": "BulkImportFindAllOrganizations",
     "isAuditLog": true,
     "level": "info",
     "message": "'get /organizations' endpoint hit by user:default/myuser",
     "meta": {},
     "plugin": "bulk-import",
     "request": {
       "body": {},
       "method": "GET",
       "params": {},
       "query": {
         "pagePerIntegration": "1",
         "sizePerIntegration": "5"
       },
       "url": "/api/bulk-import/organizations?pagePerIntegration=1&sizePerIntegration=5"
     },
     "response": {
       "status": 200
     },
     "service": "backstage",
     "stage": "completion",
     "status": "succeeded",
     "timestamp": "2024-08-26 16:41:02"
   }

Procedure

1. Configure the Bulk Import plugin by editing your app-config.yaml file to enable Orchestrator mode.

   bulkImport:
     orchestratorWorkflow: your_workflow_id
     importAPI: 'orchestrator'

   where:

   orchestratorWorkflow

   The ID of the workflow to run for each repository.

   importAPI

   The execution mode for the workflow. Enter orchestrator to enable workflow execution.

2. Verify that the Orchestrator workflow receives the following input:

   {
     "inputData": {
       "owner": "redhat-developer",
       "repo": "rhdh-plugins",
       "baseBranch": "main",
       "targetBranch": "bulk-import-orchestrator"
     },
     "authTokens": [
       {
         "token": "<github_token>",
         "provider": "github"
       }
     ]
   }

   where:

   owner

   Specifies the repository owner (organization or user name).

   repo

   Specifies the repository name.

   baseBranch

   Specifies the default branch of the Git repository (for example, main).

   targetBranch

   Specifies the target branch for the import operation. By default, this is set to bulk-import-orchestrator.

   authTokens

   Specifies the authentication tokens for the Git provider:

3. For GitHub: { token: <github_token>, provider: github }
4. For GitLab: { token: <gitlab_token>, provider: gitlab }

5. Navigate to the Bulk Import page in the sidebar and complete the following steps:

   1. Select your Git provider (for example, GitHub or GitLab).
   2. Select the projects you want to import.
6. Click import to run the workflow.

Procedure

1. Add a package with plugin name and update the disabled field in your dynamic-plugins.yaml file as follows:

   plugins:
     - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-scaffolder-backend-module-servicenow:<tag>
       disabled: false

   where:

   <tag>

   Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

   1. Find your Backstage version in the RHDH release notes preface.

   2. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.9 based on Backstage 1.45.3, use the format bs_1.45.3__<plugin-version>.

      Tip

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

   Note

   The default configuration for a plugin is extracted from the dynamic-plugins.default.yaml file, however, you can use a pluginConfig entry to override the default configuration.

2. Set the following variables in your app-config.yaml file to access the custom actions:

   servicenow:
     # The base url of the ServiceNow instance.
     baseUrl: ${SERVICENOW_BASE_URL}
     # The username to use for authentication.
     username: ${SERVICENOW_USERNAME}
     # The password to use for authentication.
     password: ${SERVICENOW_PASSWORD}

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.