Configuring Agent Requirements
Agent Requirements are conditions that specify which agents can run your build configuration. Any agent requirement is the parameter operator [value]
expression, where:
parameter
is either a predefined or a custom (user-defined) build parameter. For example, theteamcity.agent.jvm.os.name
parameter that reports which operating system is installed on the agent. Note that since requirements should identify whether an agent can run builds for this specific build configuration, you should only use parameters whose values can differ depending on the agent. For example, theteamcity.serverUrl
parameter reports the same value for any agent and is useless for defining agent requirements.operator
is a keyword that defines how to treat thevalue
part. You can choose between "equals", "starts with", "is not more than", and other operators. See this article for the complete list: Requirement Conditions.value
is compared with the actual value reported by the parameter. If it fits the specified criteria, the entire expression returnstrue
, which means this agent is compatible with (can run builds of) this specific configuration. Certain operators do not require values, for example theexists
operator checks whether the parameter value is notnull
. Thematches
anddoes not match
operators allow you to use regular expressions for comparing values.
Build Step Requirements
To ensure your build is never assigned to an agents that cannot run it, TeamCity analyzes all build configurations and lists agents that do not fit configurations' building routines as incompatible.
For example, if one of your steps runs inside a container, TeamCity filters out agents that have neither Docker nor Podman installed via the container.agent exists
requirement. Or if one of your steps references a build parameter (for example, a Command Line script prints the value of %my.custom.param%
), TeamCity uses the same exists
operator to identify agents that do not report this parameter.
How to Create a Custom Explicit Requirement
You can add custom agent requirements in both TeamCity UI and in Kotlin DSL.
To temporarily disable or permanently remove a requirement, click the drop-down menu button next to Edit. Note that implicit requirements cannot be removed or disabled since they are directly required by the build actions performed in this configuration. Add new expressions to the object MyBuildConfig : BuildType({
requirements {
exists("DotNetCoreSDK5.0_Path")
startsWith("teamcity.agent.jvm.os.name", "Windows")
}
}) See also: Requirements | Kotlin DSL Documentation |
---|
Inherited Requirements
If an agent requirement is declared in a Build Configuration Template, the requirement is also in effect for all configurations based on this template. The Agent Requirements page for these configuration marks such requirements as "inherited".
Project administrators can edit, disable, and remove inherited requirements unless they are a part of an enforced settings template.
Combining Conditions
When multiple requirements are defined, they are implicitly joined by boolean AND. For example, the following set of conditions requires that both the env.JDK_17_0
parameter AND the env.JDK_21_0
parameter exist:
There is no mechanism available for joining requirements with boolean OR.