Release Templates

Release templates serve to add a layer of consistency to the release creation process by assigning default properties (e.g., pipeline selection, initial included deployables ), prompting for variables at various points in the release lifecycle, and simplifying Release & Deployment API usage.

Release templates are application-specific, but can be easily copied into other applications using JSON text mode.

Components

Release templates consist of three primary components:

1. Pipeline - the default pipeline selection when creating a release
2. Deployables - the default deployables that are included or referenced when creating a release
3. Template Variable Prompts - defines the variable prompts that occur during release creation, build creation, and deployment in a pipeline stage. Template variable configurations are the only settings in a release template that are considered "live", so changing them can change the prompts during build creation or release deployment that are currently assigned to the template.

Template Variables and Configurations

Hierarchy

Release template variables are configurable at any of three levels:

1. Release creation - when a new share is created, inputs for the specified variables appear, and once the share is created, the corresponding Release Variables are created. These variable values can be edited later on the Release Details page.
2. Build creation - when creating a new build of a release with an assigned template, inputs for the specified variables are displayed, and once the build is created, the corresponding Build Variables will be created. These variable values can be edited later on the Build Details page.
3. Deployment to a pipeline stage - when deploying a build of a release with an assigned template, inputs are displayed on the Deploy to Stage page, and once the deployment starts, the corresponding Execution Variables will be injected into the deployment and are not editable (but they can be overridden within a deployment plan using the Set Variable statement).

Types

There are four types of Template Variables:

1. Text - a simple string value whose prompt is presented as a text box
2. Checkbox - a simple boolean value with optional description whose prompt is presented as a checkbox
3. List - a collection of multiple values defined in the template variable configuration whose prompt is presented either as a dropdown list or as a tag text box if the list is not limited to the elements specified in the configuration.
4. Dynamic List - a collection of values such as a list of BuildMaster servers, environments, or an external source (e.g. ProGet package IDs/versions). These values are extensible and can be added via List Variable Sources. The prompt is presented as a text field with auto-completed values generated from the configuration source.

Common Template Variable Configuration

Each of the four template variable types can be configured in different ways, but the following options are the same for all of them:

• Initial value - the pre-filled value that will appear in a rendered variable prompt
• Required - indicates that a value must be present to proceed with version/build creation or to perform deployment
• Obscure the value of this variable from casual viewing - indicates that a corresponding release or build variable is hidden from UI when it is created and requires additional editing permissions to view it. Note that this is not a means to "secure" a variable value, which is handled by Resource Credentials.

Creating a Release Template

To create a release template, in the context of an application, select the Releases tab in the Releases project sub-navigation menu. Although the UI editor is the recommended method for creating release templates, it is also possible to create them from a JSON object.

Default Release Template

As of BuildMaster 6.1.11, a release template named Default is automatically used for shares for which no template is selected. From the perspective of UI, this template also behaves slightly differently: it is not displayed as an associated template on the release overview page, and the release template selection option is hidden if there is only one template named Default.

Using a Release Template

Once a release template is created, it can be used in one of two places: create a new release from the UI, or the Create Release from Template API endpoint.

If there is only a single release template for an application, that release template is selected by default when a new release. Once a release is assigned to a release template, each of the 3 variable properties that contain template variable configurations will be prompted for values according to the Hierarchy section above.

A release may be assigned a different release template at any time as long as the release is active. Note, however, that this may change the variable prompts whose values are expected by a deployment plan.

JSON Format

Release Template Object

Variable Object

Deployable Object

(* indicates a required field)