Configuring Build Parameters
Parameters are name=value
pairs that can be referenced throughout TeamCity. There are three major parameter types in TeamCity:
Configuration Parameters — parameters whose primary objective is to share settings within a build configuration. You can also use these parameters to customize a configuration that was created from a template or uses a meta-runner. TeamCity does not pass parameters of this type to a build process (that is, these parameters are not accessible by a build script engine).
Environment Variables — parameters that start with the
env.
prefix. These parameters are passed to the process of a build runner similarly to the default env variables of a system.
System Properties — parameters that start with the
system.
prefix. TeamCity can pass parameters of this type to configuration files of certain runners as variables specific to a build tool.
Common Information
Parameters allow you to avoid using plain values in TeamCity UI and build scripts. Instead, you can reference a parameter by its name using the %parameter_name%
syntax. In addition, parameters can reference other parameters in their values (for example, system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar
).
Storing values in parameters allows you to:
Quickly reuse frequently used values;
Create reusable templates and meta-runners whose parameter values are overridden in target configurations;
Add flexibility to your build configurations: parameter values can be quickly altered in TeamCity UI, via the service message sent during a build, or in the Run Custom Build dialog;
Hide sensitive information that should not be visible to regular TeamCity developers;
Improve the readability of your configurations by using shorter parameter references instead of lengthy plain values, and so on.
See the following article for simple use cases where you can store values in parameters: Using Build Parameters.
Main Use Cases
Customize Template-Based Configurations
Configuration parameters allow you to create a base build configuration with parameters, extract it to the template, and override these parameters in configurations based on this template. Using this technique you can quickly duplicate your build configurations that have slight variations depending on your current task.
For example, the following build configuration has two steps and the Boolean skip.optional.step
parameter. Step #2 will or will not be executed depending on this parameter value.
If you extract a template from this configuration, you can create multiple copies of the same configuration. In those copies that do not need to run the optional step #2, override the skip.optional.step
parameter and set it to true
.
See the following section to learn more about step execution conditions: Specify Step Execution Conditions.
Pass Values to Meta-Runners
A meta-runner allows you to extract build steps, requirements, and parameters from a build configuration and create a custom build runner.
See this article for the example of an Ant-based meta-runner that utilizes the custom system.artifact.paths
parameter to publish artifacts via a corresponding service message: Preparing Build Configuration.
Specify Step Execution Conditions
You can define step execution conditions to specify whether individual steps should run. You can craft these conditions using custom and predefined configuration parameters and environment variables.
To set up step execution conditions in TeamCity UI, go to step settings and click Add condition | Other condition...
For example, you can run different shell scripts depending on the build agent's operating system.
Specify Agent Requirements
Agent Requirements allow you to specify parameter-operator-value
conditions. Only those agents that meet these conditions are allowed to build this build configuration.
You can define agent requirements using only those parameters whose values agents can report before the build starts. These parameters are:
Predefined configuration parameters available for all agents (for example,
teamcity.agent.name
).Environment variables reported by agents (for example,
env.DOTNET_SDK_VERSION
).Custom configuration parameters that are present in agents' buildAgent.properties files (for example, create a
custom.agent.parameter
in TeamCity UI and add thecustom.agent.parameter=MyValue
line to agents' properties files).
TeamCity automatically adds agent requirements depending on the configured build steps. For example, if a build step should be executed inside a Linux container, TeamCity adds requirements that specify an agent must have either Docker or Podman running on a Linux machine.
To define custom agent requirements in TeamCity UI, navigate to the Administration | <Build Configuration> | Agent Requirements tab.
In Kotlin DSL, use the requirements
block of your build configuration to define a requirement.
For example, the following condition allows only Mac agents to run builds for the parent build configuration.
The sample condition below allows builds to run only on machines with "Android" workload installed for .NET 7 SDK:
The following condition requires that an agent running builds has either Docker or Podman:
Pass Values to Simple Script Runners
You can insert references to parameters as %parameter_name%
when writing scripts for Command Line, C# Script, and Python runners.
The script below prints the checkout directory path (configuration parameter) and TeamCity server version (environment variable) to the build log.
echo "Checkout directory: %\teamcity.build.checkoutDir%"
echo "Server version: '$TEAMCITY_VERSION'"
The script below uses a reference to the build branch to obtain a file that should be copied to the target directory.
set -e -x
FILE=%\teamcity.build.branch%/fileToCopy.xml
if test -f "$FILE"; then
cp "$FILE" folderA/folderB
fi
This sample script sends the REST API request to download the "libraries.tar.gz" archive from the server (whose URL is stored as the
curl -o libraries_%\build.number%.tar.gz %\serverUrlBase%libraries.tar.gz
The following script prints the checkout directory path (configuration parameter) and TeamCity server version (environment variable) to the build log.
print(f'Current checkout directory is: %\teamcity.build.checkoutDir%')
print(f'TeamCity version is: %\env.TEAMCITY_VERSION%')
# or
print(f"TeamCity version is: {os.environ['TEAMCITY_VERSION']}")
The following script obtains the checkout directory path and appends an additional path to it:
string fullPath = Path.Combine("%\teamcity.build.checkoutDir%", "myFolder/bin");
Console.WriteLine(fullPath);
To get values of environment variables, use the Environment.GetEnvironmentVariable method:
Console.WriteLine("Predefined variable value = " + System.Environment.GetEnvironmentVariable("TEAMCITY_VERSION"));
Console.WriteLine("Custom variable value = " + System.Environment.GetEnvironmentVariable("My.Custom.Env.Variable"));
You can also add parameter references in the See this blog post for an example of using parameters in C# scripts and .NET runner: How to automate CI/CD tasks with C# Scripting in TeamCity. |
---|
Share Values Between Steps
You can use parameters to pass simple data from one step/script to another. To do this, send the setParameter
service message from a script that calculates new parameter values.
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.
Pass Values to Builders' Configuration Files
.NET, Maven, Gradle, Ant and NAnt runners allow you to reference TeamCity parameters in build configuration files. This technique allows you to pass the required values to build processes.
In .NET, pass parameter values using the $(<parameter_name>)
syntax.
The following sample .csproj
file defines two custom MSBuild targets:
To reference a parameter value in Maven and Ant, use the ${parameterName}
syntax.
To reference a parameter value in Maven and Ant, use the ${parameterName}
syntax.
For Gradle runner, TeamCity system properties can be accessed as native Gradle properties (those defined in the gradle.properties
file). If the property name is allowed as a Groovy identifier (does not contain dots), use the following syntax:
Otherwise, if the property has dots in its name (for example, build.vcs.number.1
), use the project.ext["build.vcs.number.1"]
syntax instead.
Share Values Between Chain Builds
TeamCity parameters allow you to exchange values between configurations of a build chain. See this documentation article for more information: Use Parameters in Build Chains.