Red Hat Developer Hub 1.8

Streamline software development and management in Red Hat Developer Hub

Automating the development lifecycle, improving code quality, monitoring deployments, and managing services by using tools and plugins in Red Hat Developer Hub (RHDH)

Red Hat Customer Content Services

Abstract

As a developer, you can learn how to use the platform integrated tools and services to create component catalogs, enforce code standards, manage security, and automate the software development and management workflow in Red Hat Developer Hub (RHDH).

1. Importing your team’s codebase from Git
2. Centralizing your software components in the Red Hat Developer Hub catalog for easier access
3. Importing and using an existing Software Template for faster development

1. Importing your team’s codebase from Git

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.

Red Hat Developer Hub can automate GitHub repositories onboarding and track their import status.

1.1. Enabling and authorizing Bulk Import capabilities in Red Hat Developer Hub

You can enable the Bulk Import feature for users and give them the necessary permissions to access it.

Prerequisites

You have enabled GitHub repository discovery.

Procedure

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:
dynamic-plugins.yaml fragment
```
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.
Configure the required bulk.import RBAC permission for the users who are not administrators as follows:
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

The sidebar displays a Bulk Import option.
The Bulk Import page shows a list of Added Repositories.

1.2. Importing multiple GitHub repositories

In Red Hat Developer Hub, you can select your GitHub repositories and automate their onboarding to the Developer Hub catalog.

Prerequisites

You have enabled the Bulk Import feature and gave access to it.

Procedure

Click Bulk Import in the left sidebar.
Click the Add button in the top-right corner to see the list of all repositories accessible from the configured GitHub integrations.
1. From the Repositories view, you can select any repository, or search for any accessible repositories. For each repository selected, a catalog-info.yaml is generated.
2. From the Organizations view, you can select any organization by clicking Select in the third column. This option allows you to select one or more repositories from the selected organization.
Click Preview file to view or edit the details of the pull request for each repository.
1. Review the pull request description and the catalog-info.yaml file content.
2. Optional: when the repository has a .github/CODEOWNERS file, you can select the Use CODEOWNERS file as Entity Owner checkbox to use it, rather than having the content-info.yaml contain a specific entity owner.
3. Click Save.
Click Create pull requests. At this point, a set of dry-run checks runs against the selected repositories to ensure they meet the requirements for import, such as:
1. Verifying that there is no entity in the Developer Hub catalog with the name specified in the repository catalog-info.yaml
2. Verifying that the repository is not empty
3. Verifying that the repository contains a .github/CODEOWNERS file if the Use CODEOWNERS file as Entity Owner checkbox is selected for that repository
  - If any errors occur, the pull requests are not created, and you see a Failed to create PR error message detailing the issues. To view more details about the reasons, click Edit.
  - If there are no errors, the pull requests are created, and you are redirected to the list of added repositories.
Review and merge each pull request that creates a catalog-info.yml file.

Verification

The Added repositories list displays the repositories you imported, each with an appropriate status: either Waiting for approval or Added.
For each Waiting for approval import job listed, there is a corresponding pull request adding the catalog-info.yaml file in the corresponding repository.

1.3. Managing repositories after import to stay organized

You can oversee and manage the repositories that are imported to the Developer Hub.

Prerequisites

You have imported GitHub repositories.

Procedure

Click Bulk Import in the left sidebar to display all the current repositories that are being tracked as Import jobs, along with their status.
Added
The repository is added to the Developer Hub catalog after the import pull request is merged or if the repository already contained a catalog-info.yaml file during the bulk import. Note that it may take a few minutes for the entities to be available in the catalog.
Waiting for approval
There is an open pull request adding a catalog-info.yaml file to the repository. You can:
Click the pencil icon on the right to see details about the pull request or edit the pull request content right from Developer Hub.
Delete the Import job, this action closes the import PR as well.
To transition the Import job to the Added state, merge the import pull request from the Git repository.
Empty
Developer Hub is unable to determine the import job status because the repository is imported from other sources but does not have a catalog-info.yaml file and lacks any import pull request adding it.

Note

After an import pull request is merged, the import status is marked as Added in the list of Added Repositories, but it might take a few seconds for the corresponding entities to appear in the Developer Hub Catalog.
A location added through other sources (like statically in an app-config.yaml file, dynamically when enabling GitHub discovery, or registered manually using the "Register an existing component" page) might show up in the Bulk Import list of Added Repositories if the following conditions are met:
- The target repository is accessible from the configured GitHub integrations.
- The location URL points to a catalog-info.yaml file at the root of the repository default branch.

1.4. Monitoring Bulk Import actions using audit logs

The Bulk Import backend plugin adds the following events to the Developer Hub audit logs. See Audit logs in Red Hat Developer Hub for more information on how to configure and view audit logs.

Bulk Import Events:

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 bulk import audit logs

{
  "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"
}

2. Centralizing your software components in the Red Hat Developer Hub catalog for easier access

The Red Hat Developer Hub Software Catalog is a centralized system that gives you visibility into all the software across your ecosystem, including services, websites, libraries, and data pipelines. You can use it to view ownership details and metadata for each component in one place.

The metadata for the components in your Software Catalog is stored as YAML files that live alongside your code in your version control system. The version control repositories can include one or many metadata files. Software Catalog organizes items as entities, which include Components, Resources, and APIs, and other related types. Each entity includes associated metadata such as its owner, type, and other relevant details.

By storing metadata in YAML files alongside the code, you allow Red Hat Developer Hub to process and display this information through a clear, visual interface. With the Software Catalog, you can manage and maintain your software, stay aware of all software available in your ecosystem, and take ownership of your services and tools.

The Overview page for a component provides key information such as links to the source code, documentation, dependencies, and ownership details. You can customize this page with plugins to suit specific needs.

2.1. Adding new components to your Red Hat Developer Hub instance to expand your catalog

Prerequisites

You have installed and configured the Red Hat Developer Hub instance.
You have the required permissions. See Authorization in Red Hat Developer Hub.

Procedure

You can add components to your RHDH instance using the following methods:

Register components manually using the GUI or by using your app-config.yaml with the required permissions.
Create new components by using Software Templates.
Use the bulk import plugin with the required permissions. For more information, see Bulk importing GitHub repositories.

2.1.1. Creating new components in your Red Hat Developer Hub instance

You can create new components in the Software Catalog in your RHDH instance. Red Hat Developer Hub automatically registers all components that developers or platform engineers create using Templates in the Software Catalog.

Prerequisites

You have installed and configured the Red Hat Developer Hub instance.
You have the required permissions. See Authorization in Red Hat Developer Hub.

Procedure

In your Red Hat Developer Hub navigation menu, click Catalog.
On the Catalog page, click Self-service.

2.1.2. Registering components manually in your RHDH instance

To manually register components in your RHDH instance, create a catalog-info.yaml file and register it with your Red Hat Developer Hub instance. The catalog-info.yaml file contains the metadata you wish to register for your software component.

Prerequisites

You have installed and configured the Red Hat Developer Hub instance.
You have the required permissions. See Authorization in Red Hat Developer Hub.

Procedure

In the root directory of your software project, create a file named catalog-info.yaml.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
    name: _<your_software_component>_
    description: _<software_component_brief_description>_
    tags:
         - example
         - service
    annotations:
         github.com/project-slug: _<repo_link_of_your_component_to_register>_
spec:
    type: _<your_service>_
    owner: _<your_team_name>_
    lifecycle: _<your_lifecycle>_

Commit the catalog-info.yaml file to the root of your project source code repository.
In your Red Hat Developer Hub navigation menu, go to Catalog > Self-service.
On the Self-service page, click Register Existing Component.
On the Register an existing component page, enter the full URL of the catalog-info.yaml file in your repository. For example: Artist lookup component.
Complete the wizard instructions.

Verification

Your software component is listed in the Software Catalog. You can view its details and ensure all the metadata is accurate.

2.2. Updating existing component in your Red Hat Developer Hub catalog

You can update components in the Software Catalog in your Red Hat Developer Hub instance.

Prerequisites

You have installed and configured the Red Hat Developer Hub instance.
You have the required permissions. See Authorization in Red Hat Developer Hub.

Procedure

To update components in the Software Catalog in your Red Hat Developer Hub instance, complete the following steps:

In your Red Hat Developer Hub navigation menu, click Catalog.
Find the software component that you want to edit, under Actions, click the Edit icon.
Note
This action redirects you to the YAML file on GitHub.
On your remote repository UI, update your YAML file.
Note
After you merge your changes, the updated metadata in the Software Catalog appears after some time.

2.3. Finding the right components quickly in the Red Hat Developer Hub catalog by Kind

Procedure

In your Red Hat Developer Hub navigation menu, click Catalog.
On the Catalog page, click the Kind drop-down list.
Select the type of Kind you want to filter.
Note
The available filter dropdowns vary based on the Kind you select, displaying options relevant to that specific entity type.

2.4. Finding the right component quickly in the Red Hat Developer Hub catalog by using the Filter field

Procedure

In your Red Hat Developer Hub navigation menu, click Catalog.
In the Search box, enter the text you want to use to filter the components.

2.5. Reviewing the YAML configuration of your Red Hat Developer Hub Software Catalog

You can view the Software Catalog YAML file in your Red Hat Developer Hub instance. The YAML file displays the metadata for the components in your Software Catalog.

Procedure

To view the Software Catalog YAML file in your Red Hat Developer Hub instance, complete the following steps:

In your Red Hat Developer Hub navigation menu, click Catalog.
Find the software component that you want to view, under Actions, click the View icon.
Note
These steps redirect you to the YAML file on your remote repository.

2.6. Starring key components in the Software Catalog

You can use the Add to favorites icon to add the software catalogs that you visit regularly to the Starred category.

Procedure

To quickly access the Software Catalogs that you visit regularly, complete the following steps:

In your Red Hat Developer Hub navigation menu, click Catalog.
Find the software component that you want to add as a favorite, under Actions, click the Add to favorites icon.

Verification

The starred component is listed under Your Starred Entities on your Home page.

3. Importing and using an existing Software Template for faster development

You can configure Software Templates to create software components and publish these components to Git repositories. Once the components are published to Git repositories, register these components in the Software Catalog.

A template is a form composed of different UI fields that is defined in a YAML file. Software Templates include actions, which are steps that are executed in sequential order and can be executed conditionally.

3.1. Creating a Software Template by using the Template Editor

Use the Red Hat Developer Hub Template Editor to create a Software Template.

Alternately, you can use the Template Editor to do any of the following actions:

File > Open template directory
File > Create template directory
File > Close template editor
Use the Custom Fields Explorer button to test custom fields in your templates.yaml file
View Installed Actions Documentation

Procedure

To create a Software Template by using the Template Editor templates, complete the following steps:

In your Red Hat Developer Hub navigation menu, click Catalog > Self-service. Alternatively, to go to Self-service page, in your header menu, click the (+) icon.
Click the More options icon and select Manage Templates.
Note
- The following options on the Managed Templates page do not create a software component in your Red Hat Developer Hub instance:
  Template Form Playground: Use to create and test the templates.yaml file
  Custom Field Explorer: Use to test custom fields
On the Managed Templates page, select any of the following options:
- Load Template Directory: Use to load an existing templates.yaml file
  - In your local file manager, navigate to the folder where your templates.yaml file is stored and click Select.
- Create New Template: Use to create a templates.yaml file
  1. In your local file manager, navigate to the folder where you want the Template Editor to create a templates.yaml file and click Select.
  2. On the Template Editor page, select the templates.yaml file.
  3. (Optional) You can preview and test your template specifications.
    On the Fill in some steps tab, enter text into the required fields and click Next.
    On the Repository Location tab, enter text into the required fields and click Review.
    Modify the YAML definition for the parameters of your template. For more information about these parameters, see Section 3.2, “Creating a Software Template as a YAML file”.
    Review the information for accuracy, then click Create.
  4. After the Software Template is created, import your Software Template in your RHDH instance.

Verification

Click the Catalog tab in the navigation panel.
In the Kind drop-down menu, select Template.
Confirm that your template is shown in the list of existing templates.

Next step

Import your Software Template in your RHDH instance.

3.2. Creating a Software Template as a YAML file

You can create a Software Template by defining a Template object as a YAML file.

The Template object describes the Software Template and its metadata. It also contains required input variables and a list of actions that are executed by the scaffolding service.

Template object example

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: template-name 1
  title: Example template 2
  description: An example template for v1beta3 scaffolder. 3
spec:
  owner: backstage/techdocs-core 4
  type: service 5
  parameters: 6
    - title: Fill in some steps
      required:
        - name
      properties:
        name:
          title: Name
          type: string
          description: Unique name of the component
        owner:
          title: Owner
          type: string
          description: Owner of the component
    - title: Choose a location
      required:
        - repoUrl
      properties:
        repoUrl:
          title: Repository Location
          type: string
  steps: 7
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      # ...
  output: 8
    links:
      - title: Repository 9
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: Open in catalog 10
        icon: catalog
        entityRef: ${{ steps['register'].output.entityRef }}
# ...

1

Specify a name for the Software Template.

2

Specify a title for the Software Template. This is the title that is visible on the Software Template tile in the Self-service view.

3

Specify a description for the Software Template. This is the description that is visible on the Software Template tile in the Self-service view.

4

Specify the ownership of the Software Template. The owner field provides information about who is responsible for maintaining or overseeing the Software Template within the system or organization. In the provided example, the owner field is set to backstage/techdocs-core. This means that this Software Template belongs to the techdocs-core project in the backstage namespace.

5

Specify the component type. Any string value is accepted for this required field, but your organization should establish a proper taxonomy for these. Red Hat Developer Hub instances may read this field and behave differently depending on its value. For example, a website type component may present tooling in the Red Hat Developer Hub interface that is specific to just websites.

The following values are common for this field:

service: A backend service, typically exposing an API.
website: A website.
library: A software library, such as an npm module or a Java library.

6

Use the parameters section to specify parameters for user input that are shown in a form view when a user creates a component by using the Software Template in the Red Hat Developer Hub console. Each parameters subsection, defined by a title and properties, creates a new form page with that definition.

7

Use the steps section to specify steps that are executed in the backend. These steps must be defined by using a unique step ID, a name, and an action. You can view actions that are available on your Red Hat Developer Hub instance by visiting the URL https://<rhdh_url>/create/actions.

8

Use the output section to specify the structure of output data that is created when the template is used. The output section, particularly the links subsection, provides valuable references and URLs that users can utilize to access and interact with components that are created from the template.

9

Provides a reference or URL to the repository associated with the generated component.

10

Provides a reference or URL that allows users to open the generated component in a catalog or directory where various components are listed.

3.3. Creating a new software component using Software Templates

You can create a new software component using the standard Software Templates that the platform engineers have created. The scaffolding process runs in your Red Hat Developer Hub instance.

Procedure

In your Red Hat Developer Hub navigation menu, click Catalog > Self-service.
On the Self-service page, click Choose on the Templates tile to initiate the scaffolding process for a template.
Follow the wizard instructions as you enter the required details. You can choose parameters from a set of pre-defined options.
- Optional: In the Deployment Information step, you have an option to Create Workbench for OpenShift AI.
  Note
  This step is available only for a few templates.
In the Review step, verify the parameters you have entered and click Create.
Note
- You can click Cancel to abort the software component creation during the template running step only if the current step supports the abort. The abort signal is then sent to a task and none of the following steps are executed.
- During the creation of the software component, click Show Logs to view the log information.

Verification

If your software component is not created successfully, you can review the logs on the error page. To return to the Self-service page with the same template form and your previously entered values, click Start Over.

If your Software Template is created successfully, a success page similar to the example in the following image is displayed:

3.4. Searching and filtering Software Templates in your Red Hat Developer Hub instance

You can search and filter for the Software Template that you want to use to create a new software component.

Procedure

To search and filter for a Software Template, complete the following steps:

In the Red Hat Developer Hub navigation menu, click Catalog > Self-service.
Type the name of the template you are looking for in the Search box.
- If you are looking for templates in a certain category, you can use the Categories dropdown.

3.5. Importing an existing Software Template to Red Hat Developer Hub

You can add an existing Software Template to your Red Hat Developer Hub instance by using the Catalog Processor.

Prerequisites

You have created a directory or repository that contains at least one template YAML file.
Optional: To use a template stored in a GitHub repository, you have configured Developer Hub integration with GitHub.

Procedure

In the app-config.yaml configuration file, modify the catalog.rules section to include a rule for Software Templates, and configure the catalog.locations section to point to the Software Template that you want to add, as shown in the following example:
```
# ...
catalog:
  rules:
    - allow: [Template] 1
  locations:
    - type: url 2
      target: https://<repository_url>/example-template.yaml 3
# ...
```
1
To allow new Software Templates to be added to the catalog, you must add a Template rule.
2
If you are importing templates from a repository, such as GitHub or GitLab, use the url type.
3
Specify the URL for the template.

Verification

Click the Catalog tab in the navigation panel.
In the Kind drop-down menu, select Template.
Confirm that your template is shown in the list of existing templates.

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.