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, the teamcity.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 Agent 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.