Scopes, Priority, and Lifecycle of Build Parameters
Initial Parameter Values
TeamCity parameters can obtain their values from one or multiple sources listed below.
Values from a template selected as the enforced settings template. These values cannot be disabled or overridden by users.
The Parameters tab of the Run Custom Build dialog.
Custom values entered on the Build Configuration Settings | Parameters page.
Custom values entered on the Project Settings | Parameters page. Parameters defined within a project are inherited by all its subprojects and build configurations. If required, you can override them in individual build configurations.
Values specified in a regular build configuration template.
Values specified in a build agent's configuration file (the
<AGENT_HOME>/conf/buildAgent.properties
file). For example, the following sample demonstrates how to implement a custom build agents' ranking system that you can use in Agent Requirements:// _Root project config object Project : Project({ description = "Contains all other projects" params { param("agent.tier", "") } })# An agent's "buildAgent.properties" files ###################################### # Default Build Properties # ###################################### # ... agent.tier=Platinum # ...Values reported by an agent when it connects to the TeamCity server. These values are passed to parameters that describe the agent environment. For example, the
DotNetCoreSDK7.0_Path
parameter that stores the path to .NET 7 SDK on this specific agent.Values of predefined build parameters. These parameters can collect their values on a server side in the scope of a specific build (for example, the
build.number
parameter), or on the agent side right before a build starts (for example, theteamcity.agent.work.dir.freeSpaceMb
parameter).
Parameters' Priority
The list above also ranges parameter value sources by priority, from highest to lowest. That is, if the same parameter retrieves different values from different sources, a value from the topmost source in this list is applied. For example, if the my.parameter
is defined inside an agent configuration file and on a build configuration settings page in TeamCity UI, the value from the configuration settings page wins.
Changing Parameter Values During a Build
TeamCity parameters can change their values as a build progresses through its stages. This can happen automatically, due to the nature of the value reported by a parameter, or in response to operations performed during a build.
For example, the teamcity.agent.work.dir.freeSpaceMb
parameter that reports the available agent disk space changes its value as builds checkout new source files and generate new artifacts and logs.
If you need to manually change a TeamCity parameter from inside a build step, send the following service message:
In the following configuration, a C# script checks the current day of the week and writes it to the day.of.week
parameter. A subsequent Python runner then uses the updated parameter value.
Checking Parameter Values
In TeamCity UI
To check current values of agent parameters, navigate to Agents | Parameters report and enter the property whose value you need to check.
You can also click any build agent to open the agent details page, and switch to the Parameters tab to view all parameters reported by this specific agent.
To view which values parameters had during a specific build, open this build's results page and switch to the Parameters tab.
This page has two tabs:
Parameters — lists values for all configuration parameters, system properties, and environment variables. You can tick a related checkbox to view only those parameters that changed their values during this build.
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.
Using REST API
To check initial and actual parameter values of the specific build via REST API, send GET requests to the /app/rest/builds/[{buildLocator}](https://www.jetbrains.com.cn/en-us/help/teamcity/rest/buildlocator.html)
endpoint and specify required payload fields according to the Build schema.
/app/rest/builds/{buildLocator}?fields=originalProperties(*)
— returns user-defined parameters from the build configuration and their default values./app/rest/builds/{buildLocator}?fields=startProperties(*)
— returns all parameters reported by an agent and their values at the time the build started./app/rest/builds/{buildLocator}?fields=resultingProperties(*)
— returns all parameters reported by an agent and their values by the time the build finished.
You can also check initial and final values of the specific parameter. To do this, specify the name of the target parameter.
For example, if you run a custom build for the sample project illustrated in the Changing Parameter Values During a Build section, send the following query to check the day.of.week
parameter values.
If this build runs on Wednesday and you pass Sunday as the day.of.week
parameter value via the Run custom build dialog, the response payload will contain the following values:
originalProperties
returns Monday (the default value stored in the build configuration).startProperties
returns Sunday (the value from the Run custom build dialog, has a priority over the default value from the build configuration).resultingProperties
returns Wednesday (the value calculated during the build and written via the service message).