Provisioning Release Templates in Backstage Using YAML

This guide explains how to provision Release Templates using YAML configuration files and the XL CLI actions in Backstage. You can provide Inline YAML or use files stored in a GitHub repository.

Prerequisites

• Install Scaffolder Backend Module to allow Backstage to run templates and actions..
• Install Digital.ai Plugin Scaffolder Backend Module to run xlcli:apply command.
• Install RoadieHQ to use the fs:write action, which saves the YAML file to a temporary location in the Scaffolder workspace.
• The app-config.yaml file is configured with environment-specific hostnames, target and tokens. To learn more about Backstage configuration files, see Backstage Configuration Files.
• XL CLI is installed and accessible in the Backstage action context.
• A GitHub repository is available if using repository-based YAML files.
• Ensure that a Release instance is configured in your Backstage application.

Set Up Backstage Templates

You can set up and preview templates in Backstage using either local files or GitHub integration. Choose the option that works best for your environment.

Option 1: Use Local Files

Store your template files inside appropriately named folders.

For example, you might create folders such as xl-cli-yaml-inline or xl-cli-github and place your template.yaml file inside each folder.

1. Copy the folders containing your template files to the examples folder in your Backstage root directory.

2. Add entries to your app-config.yaml file to reference the template files. For example:

     - type: file
       target: ../../examples/xl-cli-yaml-inline/template.yaml
       rules:
         - allow: [ Template ]
     - type: file
       target: ../../examples/xl-cli-github/template.yaml
       rules:
         - allow: [ Template ]

   note

   Update the target paths as needed to match the location and names of your folders and template files.

3. Restart Backstage.

   Once set up, you can preview the templates in the Backstage catalog.

   

   

Option 2: Use GitHub Integration

1. Set up the GitHub integration support. For more information, see Github integration

     integrations:
       github:
         - host: github.com
           This is a Personal Access Token or PAT from GitHub. You can find out how to generate this token, and more information
           about setting up the GitHub integration from the Github Integration guide above
           token: <token>

2. Restart Backstage.

3. In your localhost, open catalog-import and import both templates using their GitHub URLs:

   • Inline YAML Template

   • GitHub YAML Template

   note

   These are example templates. Use them for reference only.

   After import, the templates will appear in your Backstage catalog. You can then preview them.

   Once set up, you can preview the templates in the Backstage catalog.

   

   

Action Parameters

The action reads configuration from app-config.yaml and runs xlcli:apply command to apply the YAML.

Parameter	Description
product	Operation type: xl-deploy or xl-release.
releaseInstance	Name of the Release instance.
yamlFilePath	Path to the YAML file. This can be inline content or a GitHub file path.

Provision Release Template Using Inline YAML

1. In the Backstage sidebar, click Create and select Provisioning Digital.ai Release by applying Inline YAML using the XL CLI tile.

2. Select xl-release as the product.

3. Paste the YAML content inline.

4. Select the Release instance.

5. Specify the file path where the YAML file should be stored.

6. Click Review to confirm your inputs.

   

7. Click Create to start template creation.

   This will create resources as defined in your YAML configuration.
   For example, you can create templates in xl-release based on the provided YAML.

This will create resources, in this case Release templates, as defined in your YAML configuration.

Provision Release Template Using YAML from GitHub

1. In the Backstage sidebar, click Create and select the Provisioning Digital.ai Release by applying YAML from GitHub using the XL CLI tile.
2. Select xl-release as the product.
3. Provide the GitHub URL in the provided field.
4. Select the Release instance.
5. Specify the file path where the YAML file should be stored.
6. Click Review to confirm your inputs.
7. Click Create to start template creation.

This will create resources, in this case Release templates, as defined in your YAML configuration.