Chapter 4. About Software Templates

Procedure

1. Locate the Software Template object YAML file where you want to add the provenance information and add a step that uses the catalog:scaffolded-from action. This action links the resulting catalog entity back to the source template.

2. Optional: To track the template version (for example, v1.0 versus v1.5), include the catalog:template:version action in the steps section. The following code block is an example to adding versioning action to the steps section:

   steps:
     - id: create-provenance-annotation
       name: Append the entityRef of this template to the entityRef
       action: catalog:scaffolded-from
     - id: create-version-annotation
       name: Create Template Version Annotation
       action: catalog:template:version
       input:
         templateVersion: ${{ parameters.version }}
     - ... other steps ...

   Copy to Clipboard Toggle word wrap

   where:

   steps:input:templateVersion

   Reads the version parameter

   Note

   The catalog:template:version action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity.

3. In your Red Hat Developer Hub app-config.yaml file, configure the catalog.locations section to point to the Software Template that you want to add. You might need to add Template to the global catalog.rules.allow list or add a granular rule to the location to allow for Software Templates ingestion, as shown in the following example:

   # ...
   catalog:
     locations:
       - type: url
         target: https://<repository_url>/example-template.yaml
         rules:
           - allow: [Template]
   # ...

   Copy to Clipboard Toggle word wrap

   where:

   catalog.locations.type

   Enter the url type if you are importing templates from a repository, such as GitHub or GitLab.

   catalog.locations.target

   Enter the URL for the template.

   catalog.locations.rules.allow

   Enter the Template rule to allow new Software Templates to be added to the catalog.

1. In the Red Hat Developer Hub navigation menu, go to Catalog and locate the newly created catalog component.
2. To view the underlying data that links the entity to the template, select the INSPECT ENTITY option.

3. To verify provenance annotations, complete the following steps:

   1. Select the YAML Raw or JSON Raw view and verify the presence of the data item for the scaffoldedFrom link.

   2. Optional: If versioning was included, verify the presence of the backstage.io/template-version annotation.

      Note

      If you publish the catalog component to an external repository (such as Git), the component file in that repository must also contain the backstage.io/template-version annotation.

1. In the Red Hat Developer Hub navigation menu, click Catalog, use the filters to find and select the Software Template you wish to inspect.
2. In the Software Template detail page, click the Dependencies tab. This view lists all catalog entities such as components, resources, and systems that reference this template, including any version information if configured.

Procedure

1. Enable the template sync and notification plugins in your RHDH dynamic-plugins.yaml file:

   plugins:
   # Enables the core template synchronization logic
     - package: './dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-scaffolder-relation-processor'
       disabled: false
   # Required only if you want to receive notifications for new pull requests
     - package: './dynamic-plugins/dist/backstage-plugin-notifications'
       disabled: false

   Copy to Clipboard Toggle word wrap
2. Open your RHDH app-config.yaml file.

3. Configure the pull request (PR) feature by adding the following configuration:

   scaffolder:
     pullRequests:
       templateUpdate:
         enabled: true

   Copy to Clipboard Toggle word wrap

4. Optional: Enable notifications to alert entity owners when a PR is created:

   scaffolder:
     notifications:
       templateUpdate:
         enabled: true

   Copy to Clipboard Toggle word wrap
5. Restart the Red Hat Developer Hub instance to apply the changes.

Verification

1. Update the version of a source template in its repository.
2. Navigate to a repository scaffolded from that template.
3. Confirm that a new pull request named [component-name]/template-upgrade-v[version] exists.