TeamCity Cloud 2023.09 Help

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.

See where you can use parameter references.

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.

Build parameters tab

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 (View Chart) allows you to check how these values trend throughout build runs.

Last modified: 19 May 2023