Skip to end of metadata
Go to start of metadata

Build Parameters provide you with flexible means of sharing settings and a convenient way of passing settings into the build.

On this page:

Types of Build Parameters

Build parameters are name-value pairs, defined by a user or provided by TeamCity, which can be used in a build.

There are three types of build parameters:

  • Environment variables (defined using "env." prefix) are passed into the spawned build process as environment
  • System properties (defined using "system." prefix) are passed into the build scripts of the supported runners (e.g. Ant, MSBuild) as build-tool specific variables
  • Configuration parameters (no prefix) are not passed into the build and are only meant to share settings within a build configuration. They are the primary means for customizing a build configuration which is based on a template or uses a meta-runner .

There is a set of predefined parameters provided by TeamCity and administrators can also add custom parameters.

The parameters can be defined at different levels (in order of precedence):

  • a specific build (via Run Custom Build dialog)
  • Build Configuration settings (the Parameters page of Build Configuration settings) or Build Configuration Template
  • Project settings (the Parameters page of the Project settings). These affect all the Build Configurations and Templates of the project and its subprojects.
  • an agent (the <Agent home>/conf/buildAgent.properties file on the agent)

Any textual setting can reference a parameter which makes the string in the format of %parameter.name% be substituted with the actual value at the time of build.
If there is a reference to a parameter which is not defined, it is considered an implicit agent requirement so the build will only run on the agents with the parameter defined.

Defining Build Parameters in Build Configuration

On the Parameters page of Build Configuration settings you can define the required system properties and environment variables to be passed to the build script and environment when a build is started. Note that you can redefine them when launching a Custom Build.

Build Parameters defined in a Build Configuration are used only within this configuration. For other ways, refer to Project and Agent Level Build Parameters.

Any user-defined build parameter (system property or environment variable) can reference other parameters by using the following format:

Using Build Parameters in Build Configuration Settings

In most Build Configuration settings you can use a reference to a Build Parameter instead of using the actual value. Before starting a build, TeamCity resolves all references with the available parameters. If there are references that cannot be resolved, they are left as is and a warning will appear in the build log.

To make a reference to a build parameter, use its name enclosed in percentage signs, e.g.: %teamcity.build.number%

Any text appearing between percentage signs is considered a reference to a property by TeamCity. If the property cannot be found in the build configuration, the reference becomes an implicit agent requirement and such build configuration can only be run on an agent with the property defined. The agent-defined value will be used in the build.

If you want to prevent TeamCity from treating the text in the percentage signs as reference to a property, use two percentage signs. Every occurrence of "%%" in the values where property references are supported will be replaced to "%" before passing the value to the build. e.g. if you want to pass "%Y%m%d%H%M%S" into the build, change it to "%%Y%%m%%d%%H%%M%%S"

Where References Can Be Used

Group of settings

References notes

Build Runner settings, artifact specification

any of the properties that are passed into the build

User-defined properties and Environment variables

any of the properties that are passed into the build

Build Number format

only Predefined Server Build Properties

VCS root and checkout rules settings

any of the properties that are passed into the build

VCS label pattern

system.build.number and Server Build Predefined Properties

Artifact dependency settings

only Predefined Server Build Properties

If you reference a build parameter in a build configuration, and it is not defined there, it becomes an agent requirement for the configuration. The build configuration will be run only on agents that have this property defined.

Password fields can also contain references to parameters, though in this case you cannot see the reference as it is masked as any password value.

For details on using and overriding parameters from dependencies, please refer to this section.

Using Build Parameters in VCS Labeling Pattern and Build Number

In Build number pattern and VCS labeling pattern, you can use %[env|system].property_name% syntax to reference the properties that are known on the server-side. These are server and reference predefined properties and properties defined in the settings of the build configuration on the Parameters page.
For example, VCS revision number: %build.vcs.number%.

Using Build Parameters in the Build Scripts

All build parameters starting with "env." prefix (environment variables) are passed into the build's process environment (omitting the prefix).

All build parameters starting with "system." prefix (system properties) are passed to the supported build script engines and can be referenced there just by the property name (without "system." prefix):

  • For AntMaven and NAnt use ${<property name>}
  • For MSBuild (Visual Studio 2005/2008 Project Files) use $(<property name>). Note that MSBuild does not support names with dots ("."), so you need to replace "." with "_" when using the property inside a build script.
  • For Gradle: the TeamCity system properties can be accessed as Gradle properties (similar to the ones defined in the gradle.properties file) and are to be referenced as follows:
    a) name allowed as Groovy identifier (the property name does not contain dots): 

    b) name not allowed as Groovy identifier (the property name contains dots, e.g. build.vcs.number.1): project.ext["build.vcs.number.1"]

    Icon
    Using teamcity["<property name>"] is not recommended, although still supported.

When TeamCity starts a build process, the following precedence of the build parameters is used (those on top have higher priority):

    • parameters from the teamcity.default.properties file.
    • pre-defined parameters.
    • parameters defined in the Run Custom Build dialog.
    • parameters defined in the Build Configuration.
    • parameters defined in the Project (the parameters defined for a project will be inherited by all its subprojects and build configurations. If required, you can redefine them in a build configuration).
    • parameters defined in a template (if any).
    • parameters defined in the agent's buildAgent.properties file.
    • environment variables of the Build Agent process itself.

The resultant set of parameters is also saved into a file which can be accessed by the build script. See teamcity.build.properties.file system property or TEAMCITY_BUILD_PROPERTIES_FILE environment variable description in Predefined Build Parameters#Agent Build Properties for details.



See also:

  • No labels

1 Comment

  1. This is related to branch parameters.  I would like to know if there is ability to configure branch specific variables like version. 

    Example: my dev branch has two variables (MajorVersion and MinorVersion).  The minor version is the parameter that needs to be different.  My dev branch is a higher MinorVersion number than my master branch MinorVersion. 

    Another example relates to Octopus Deploy by identify the channel a build package is sent.  So like before our dev branch goes to our dev channel, but our master branch goes to our release channel.