BuildMaster Documentation

Configuration Variables

  • Last Modified: 2018-12-10

Variables allow for extreme flexibility when modeling your deployment plans, and configuration variables allow you to have the same plan run differently across different servers and environments.

You can define configuration variables at different scopes (release, server, environment, global, etc), and then reference those variables in your plan when using Operations, If/Else Blocks, Loop Blocks, etc. You can also create a runtime variable in a plan itself.

Cascading Variables

Configuration Variables cascade, which means that you can define a variable of the same name in multiple places, and the correct value will be resolved at runtime. For example, if you define a variable named $HDarsPath on the Testing environment, when a plan runs against a server in the Testing environment, that variable will resolve at runtime.

If you also defined $HDarsPath on a single server in the Testing environment, then that value would be used instead.

This allows for reusing Plans and Templates without having to change local variables. There are times when it may be appropriate for variables to have different values when they are used different places, and BuildMaster allows for this.

Resolution Rules

The variable definition that's the "closest" match to the current context is used. This is determined as follows:

  • Runtime Variables (more info)
  • Deployment
  • Build
  • Release
  • Deployable
  • Application
  • Application Group
  • Pipeline Stage
  • Pipeline
  • Server
  • Server Role
  • Environment
  • Global
  • Legacy variables (more info)

Multiple Scopes

You can also assign multiple scopes to a configuration variable; for example, you could define a variable that's associated with both the Testing environment and the hdars-web role. A multi-scope variable simply adds precedence to the highest-scope (Promotion is still "closer" than a Environment + Application).

However, this get can get a bit tricky as the resolution rules are simply not intuitive, so we generally discourage this use. You can create multi-scoped variables from only the Administration section, and they are visible (but not editable) on servers, server roles, etc., they are associated with.

Variable Types

Configuration variable values may be set to any of the 3 runtime types. Configuration variable values with the following syntax will resolve to the associated type:

  • list - expression follows the format: @(item1, item2, ...)
  • map - expression follows the format: %(key1: value1, ...)
  • string - the default, any values that do not conform to the above 2 formats

A variable value is parsed as if it were an OtterScript string, where the same parsing rules apply, primarily that runtime variables are evaluated.

Because of this, a value can be escaped with the backtick character (i.e. `) if the value is meant to be a literal string but happens to conform to the format of one of the other types, for example: `@(some attribute) will resolve to a literal string @(some attribute) instead of a list containing a single element some attribute .


Variable permissions are dependent upon the context they are edited and are evaluated eagerly such that if the qualification of an earlier rule is met, the consequence is validated and processing ends. The rules are as follows:

  1. If a release is in context, then Releases_Manage is required
  2. If a deployable is in context, then Applications_Manage is required for the deployable's associated application (or source application if imported)
  3. If a server or environment is in context, then Infrastructure_Manageis required
  4. If none of the previous qualifications match, then privileges are evaluated against Applications_Manage for the application or application group in context

Sensitive Variables

Configuration variables may be marked "sensitive" which means that their values are only generally visible with manage permissions. This is not to be used for security purposes, only to replace the value on view-only pages with (hidden). However, anyone that is able to edit a deployment plan could simply call Log-Information $SensitiveVariable; to view the value.

The secure option for storing passwords, connection strings, or other values intended to be encrypted is Resource Credentials, as they require special permissions to manage, and (as per Inedo Extensibility guidelines) should never be written to any logs.

JSON Format & Bulk Editing

Variables at specific scopes can be edited in bulk as a JSON document at any of the scopes as defined in the resolution rules except for Execution and Promotion. The bulk JSON files are defined as a single root object with property/value pairs in one of two formats, either strings for both name and value, or a string name and variable object value. String values in both cases follow the variable types format above and are not JSON arrays/maps.

Full JSON Example

    "myList": "@(this, is, a, list, another value)",
    "myMap": "%(key: value, anotherKey: anotherValue, someList: @(a, b, c))",
    "mySensitiveList": {
        "value": "@(hide, from, people, walking, behind, me)",
        "sensitive": true
    "myString": "This is a simple string"

Variables API

Variables are configurable using the Variables Management API.

Custom Value Renderers

Variable value renderers are used to control or modify how a specific variable's value is rendered on an overview page. This can be used to support use-cases such as:

  • Linking to another page within BuildMaster
  • Linking to an external tool
  • Displaying a subset of properties of a map
  • Adding customized styles or images to a value
  • Cleanup of names that are too long or unreadable

A value renderer may be specified at the system, application group, or application level, and applies to variables displayed on the following pages:

  • Build overview
  • Release overview
  • Application settings
  • Pipeline details

Adding a Custom Renderer

To add a custom renderer, visit the Administration > Variables > Value Renderers tab, and enter the name and scope of the variable that will use the custom renderer.

Only non-legacy variables are considered when applying a value renderer. Additionally, variables denoted as sensitive in the UI will be rendered as (hidden) regardless if a value renderer matches or not.

Value Renderer Format

A value renderer is specified as HTML. The rendered HTML also considers variable functions in context, including for example: $BuildNumber, $Substring(...), and $ApplicationName. To access the variable's value within the renderer itself, use $Value (or @Value/%Value depending on type).

Because values are rendered as HTML, BuildMaster administrators (i.e. you) are responsible for ensuring that values are either fully-trusted (i.e. only trusted parties create safe values), or that they are properly sanitized to prevent Cross Site Scripting attacks, malformed HTML, and more. A number of helpful functions are included in the InedoCore extension to mitigate these risks such as $HtmlEncode(), $UrlEncode(), and $JsEncode().


  • Simple Substring
  • 3-property Map
  • Custom Image
$Substring($Value, 0, 10)...

Initial value: This value is too long to fit on the page

Rendered as: This value...

<a href="%Value.Href?queryData=$UrlEncode(%Value.Data)">$HtmlEncode(%Value.Text)</a>

Initial value: %(Text: Some link text..., Href:, Data: "some string")

Rendered as: Some link text...

<img style="max-width: 150px;" src="/resources/images/logos/proget-logo.png" alt="ProGet Logo" title="$HtmlEncode($Value)" />

Initial value: Some text that appears on hover

Rendered as: ProGet Logo

For other examples, see the examples section in the Builds & Continuous Integration documentation.

Legacy Configuration and Release Variables

If you used configuration variables prior to BuildMaster 5.2 and earlier, see KB#1128: Legacy Configuration and Release Variables for more information on how legacy and non-legacy variables interact.

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! .