Scopes, Priority, and Lifecycle of Build Parameters

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

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.

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%!')"
            }
        }
    }
})

warning

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()
        }
    }
})