Using Build Parameters
This article explains how to use build parameters to share settings within a build.
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 plain-text 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 respective warning appears in the build log.
To reference a build parameter, use its name enclosed in percentage characters: for example, %teamcity.build.number%
.
Password fields can also contain references to parameters. Note that in this case, you cannot see the reference when entering or editing it, as it is masked by asterisks.
For details on reusing or overriding parameters within a build chain, refer to this section.
Using Build Parameters in VCS Labeling Pattern and Build Number
In the build number pattern or VCS labeling pattern, you can use the %<prefix>.parameter_name%
syntax to reference any parameter known by TeamCity:
Predefined parameters of a server or build configuration.
Custom build parameters added on the Build Configuration Settings | Parameters page.
For example, a VCS revision number can be specified as %build.vcs.number%
.
Using Build Parameters in Build Scripts
All build parameters starting with the env.
prefix (environment variables) are passed into a build's process environment without the env.
prefix.
All build parameters starting with the system.
prefix (system properties) are passed to the build script engines and can be referenced there by the parameter name, without the system.
prefix. However, you need to use this prefix to access these parameters in the TeamCity UI or, for example, in the Command Line runner.
The following syntax will work in a build script (not in TeamCity settings):
For .NET, use
$(<parameter_name>)
.MSBuild does not support names with dots (
.
), so you need to replace.
with_
when using the parameter inside a build script.The
nuget push
andnuget delete
commands do not support parameters.
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:The name allowed as a Groovy identifier (the property name does not contain dots):
println "Custom user property value is $\{customUserProperty\}"The name not allowed as a Groovy identifier (the property name contains dots: for example,
build.vcs.number.1
):project.ext["build.vcs.number.1"]
Where References Can Be Used
This is where parameter references can be used in TeamCity:
Settings | Description |
---|---|
Build runner settings, artifact specification | Any of the parameters that are passed into the build. |
User-defined parameters and environment variables | Any of the parameters that are passed into the build. |
Build number format | |
VCS root and checkout rules settings | Any of the parameters that are passed into the build. |
VCS label pattern |
|
Artifact dependency settings |
Example Workflow
Let's try to define a build parameter on a build configuration level and use it in a build step.
In this example use case, we will add a configuration parameter containing your server URL. Then, we will use its value as the base part of the URL to download a certain file via a command line. To do this:
Go to Build Configuration Settings | Parameters.
Click Add new parameter.
Enter the parameter's name and value. Leave Configuration parameter as its Kind.
Name:
serverUrlBase
Value:
https://<yourServerDomain>.com/
Save the parameter.
Go to Build Steps.
Click Add build step.
Choose the Command Line runner type.
In the Custom script field, enter the following command:
For a build with the number 1234
, this command will be resolved as follows:
Save the build step and run a new build.
When executing this step in a build, TeamCity will download the libraries.tar.gz
archive from your server and save it in the checkout directory as an archive with the new name, depending on the current build's number. TeamCity generates a unique build number for each starting build and saves it as this build's build.number
parameter, which we referenced in the new archive name. Such predefined parameters can be accessed within build steps in the same way as parameters you add manually. You can find the list of other predefined parameters here.
You can follow this guide in your own configuration: just substitute the archive name and server URL with real values.
Parametrized build settings and scripts is one of the main advantages of TeamCity, and using them will significantly boost your pipelines' capabilities.