Configuring Build Parameters
Build parameters are name-value pairs, defined by a user or provided by TeamCity, which can be used in a build. They help flexibly share settings and pass them to build steps.
This article explains how to configure build parameters. See how to use them inside build settings and build scripts.
Types of Build Parameters
There are three types of build parameters in TeamCity:
Environment Variables
Environment variables can be passed into a spawned build process as into an environment.
They are defined by the env. prefix.
System Properties
System properties can be passed into build scripts of certain runners as variables specific to a build tool.
They are defined by the system. prefix.
Configuration Parameters
Configuration parameters are not passed into a build process 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.
They come with no prefix.
Parameter Name Restrictions
The names of configuration parameters must contain only the [a-zA-Z0-9._-*] characters and start with an ASCII letter.
Predefined Build Parameters
TeamCity provides a set of predefined parameters that can be used within a build configuration settings or directly inside build steps. For example, you can access the current build's number by calling the respective parameter generated by TeamCity. See the list of predefined parameters for details.
Custom Build Parameters
In Build Configuration Settings | Parameters, project administrators can define build parameters for the current build configuration. As soon as a new build starts in this configuration, TeamCity passes these parameters to its build scripts and environment.
Build parameters defined in a build configuration are used only within this configuration. See how to define them on a project or agent level.
Any user-defined build parameter (system property or environment variable) can reference other parameters as follows: %system.parameter_name% or %env.parameter_name%. For example, system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar.
Read more about parameter references below.
You can also configure a parameter's type, so the parameter is displayed as a UI field in the Run Custom Build dialog. This way, users will be able to use the UI dialog to quickly change the parameter's value in the next build run.
Parameter References
Most text-field settings in TeamCity support referencing a build parameter as a variable. If you enter a string in the %parameter.name% format, TeamCity will substitute it with the actual value during the build.
If a build references a parameter which is not defined, TeamCity will consider it an implicit agent requirement: the build will only run on the agents where this parameter is defined.
The references to parameters which names do not satisfy the above restrictions do not create an implicit requirement and are ignored.
Check Parameter Values After a Build
When a build finishes, open the Parameters tab on the Build Results Page to view actual (at the time of this build) values for all parameters.
This page has two tabs:
Parameters — lists values for all configuration parameters, system properties, and environment variables. Highlights parameters that were added/modified in custom builds.
Statistic values — lists all statistics values reported for the build (for example, build success rate or time required to check out a remote repository). The View Chart button (
) allows you to check how these values trend throughout build runs.