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, the teamcity.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, the teamcity.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 the value 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 returns true, which means this agent is compatible with (can run builds of) this specific configuration. Certain operators do not require values, for example the exists operator checks whether the parameter value is not null. The matches and does 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.

Navigate to build configuration settings (Administration | <Your Configuration>) and switch to the Agent Requirements tab. This page displays which agents are currently eligible to run your build configuration based on which building routines it performs.
Click the Add new requirement button.
Choose a parameter, a condition, and enter a value to create a new expression. Since TeamCity scans parameters reported by agents, it shows suggestions as you type parameter names and values.
Click Save. Your list of compatible and incompatible agents will be updated. If TeamCity is unable to find agents that satisfy your new condition, a corresponding warning is displayed next to the requirement. Running such build configuration results in the build waiting in the queue with the "There are no idle compatible agents which can run this build" status.

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 requirements block of your build configuration.

object MyBuildConfig : BuildType({
requirements {
      exists("DotNetCoreSDK5.0_Path")
      startsWith("teamcity.agent.jvm.os.name", "Windows")
   }
})

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:

requirements {
    exists("env.JDK_17_0")
    exists("env.JDK_21_0")
}

There is no mechanism available for joining requirements with boolean OR.

Last modified: 01 February 2024