BuildMaster Documentation

Release Templates

  • Last Modified: 2018-06-08

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

Release templates are scoped per-application, but can be easily copied into different applications via the JSON text mode.

Components

Release templates consist of 3 primary components:

  1. Pipeline - the default pipeline selection when creating a release
  2. Deployables - the default deployables to be included or referenced when creating a release
  3. Template Variable Prompts - defines the variable prompts that occur at release creation, release package creation, and deployment to a pipeline stage. The configurations for template variables are the only settings in a release template that are considered "live", such that changing them could change the prompts when release packages are created or deployed for releases currently assigned to the template.

Template Variables and Configurations

Hierarchy

Release template variables are configurable at any of 3 levels:

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

Types

There are 4 types of Template Variables:

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

Common Template Variable Configuration

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

  • Initial value - the pre-populated value that will appear in a rendered variable prompt
  • Required - indicates that a value must be present to continue creating the release/package or to deploy
  • Obscure the value of this variable from casual viewing - indicates that when a corresponding release or release package variable is created, that it is hidden from the UI and will require additional edit permissions to view it. Note that this is not a means to "secure" a variable value which is handled through Resource Credentials.

Creating a Release Template

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

Using a Release Template

Once a release template is created, it can be used in one of two places: either creating 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 selected by default when creating a new release. Once a release is assigned a release template, any of the 3 variables properties that contain template variable configurations will then prompt for values as per the Hierarchy section above.

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

JSON Format

Release Template Object

Name* a string representing the name of the release template
Pipeline* a string representing the name of the default pipeline during release creation
ReleaseVariables an array of Variable objects, each object represents a variable prompt that occurs during release creation
PackageVariables an array of Variable objects, each object represents a variable prompt that occurs during release package creation
DeploymentVariables an array of Variable objects, each object represents a variable prompt that occurs during deployment to a specified pipeline stage (or all stages)
DefaultDeployableOption a string value, one of:
  1. PreviousRelease: default deployables will be identical to the highest-sequenced release
  2. PreviousReleaseSameTemplate: default deployables will be identical to the highest-sequenced release that is also associated with this release template
  3. SpecificVersions: (advanced) default deployables are not included in the release, but referenced and assigned specific release numbers (requires Deployables property values with ReferencedReleaseNumber set)
Deployables an array of Deployable objects

Variable Object

Name* a string representing the name of the variable, this value is unique per each ReleaseVariables, PackageVariables properties, and unique in DeploymentVariables section if all names are associated with a PipelineStageName property
Description a string describing the variable that if supplied, is displayed in the UI instead of the variable name
InitialValue a string representing the initial value of a variable (i.e. the text or selected list value when prompted)
Required a boolean indicating whether a prompted value must be supplied
Sensitive a boolean indicating whether a value is obscured from the UI
Type a string indicating the type of the variable, one of: Text, List, DynamicList, or Checkbox
PipelineStageName a string representing the name of the pipeline stage the variable applies to, null/empty representing all stages. This value is ignored if not under the release template's DeploymentVariables property
ListValues an array of possible List variable values. This property is ignored if the Type is not "List"
ListMultiple a boolean indicating whether selection of multiple items in a List variable is allowed
ListRestrict a boolean indicating whether prompted items are restricted to values in ListValues
ListSourceDescription (automatically generated for informational purposes and not settable)
ListSourceXml a persisted XML string containing the serialized List Source configuration, this value is for informational/copying purposes and is not recommended to be configured manually as text
ListVariableSource (automatically generated for informational purposes and not settable)

Deployable Object

Name* a string representing the name of the deployable
ReferencedReleaseNumber a string representing the release number of the deployable to reference, this value is required if the DefaultDeployableOption property is set to SpecificVersions

(* indicates a required field)

Have a question? Try the Q&A Forum

Our documentation is now Open Source and on GitHub. We highly encourage our users to contribute and get involved! .