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:

echo "##teamcity[setParameter name='myParam1' value='TeamCity Agent %\teamcity.agent.name%']"

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.

object MyBuildConf : BuildType({
    params {
        param("day.of.week", "Monday")
    }
    steps {
        csharpScript {
            name = "Check the current day"
            content = """
            if ("%\day.of.week%" != DateTime.Today.DayOfWeek.ToString()) {
              string today = DateTime.Today.DayOfWeek.ToString();
              string TCServiceMessage = "##teamcity[setParameter name='day.of.week' value='" + today + "']";
              Console.WriteLine(TCServiceMessage);
            }
        """.trimIndent()
        }
        python {
            name = "Welcome message"
            command = script {
                content = "print('Hello %\teamcity.build.triggeredBy.username%, today is %\day.of.week%!')"
            }
        }
    }
})

Note that using the setParameter service message overrides the parameter value only in the scope of the current build or build chain. To permanently override a parameter value, send the REST API request from your build step like shown below:

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object UpdateBuildVersion : BuildType({
name = "Update Build Version"

    steps {
        script {
            id = "simpleRunner"
            scriptContent = """
                version=%\build.version%
                ((version=version+1))
                
                curl --location --request PUT 'http://<server_URL>/app/rest/projects/<project_name>/parameters/build.version' \
                --header 'Accept: */*' \
                --header 'Content-Type: text/plain' \
                --header 'Authorization: Bearer your_token' \
                --data ${'$'}version
            """.trimIndent()
        }
    }
})

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/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.

curl -L \
  https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=\
    originalProperties($locator(name:(value:(day.of.week),matchType:matches)),property),\
    startProperties($locator(name:(value:(day.of.week),matchType:matches)),property),\
    resultingProperties($locator(name:(value:(day.of.week),matchType:matches)),property)

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).

Last modified: 18 September 2024