Configuring Agent Requirements

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.

Explicit requirements are requirements manually configured in the Agent Requirements section of build configuration settings or in Kotlin DSL.

1. Open configuration settings and navigate to the Agent Requirements settings tab. This page displays which agents are currently eligible to run your build configuration based on which building routines it performs.

   

2. Click the Add new requirement button.

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

   

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

   

Kotlin DSL

In Kotlin DSL, add a new expressions to the requirements block of your build configuration to create an explicit requirement.

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

See also: Requirements | Kotlin DSL Documentation

To temporarily disable or permanently remove a requirement, click the drop-down menu button next to Edit.

tip

You can check which values different agents return for the given parameter before crafting an agent requirement. To do so, navigate to Agents | Parameters Report and enter a required parameter name.

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.

Build steps requirements are requirements that were not manually created by a project administrator. They arise automatically based on what configuration steps are configured to do.

For example, if one of your steps is configured to run inside a container, an agent assigned to process this build must have a container engine (Docker or Podman). For that reason, TeamCity automatically adds the docker.server.osType exists parameter. Agents that do not report this parameter will not be assigned to new builds of this configuration.

Similarly to build steps requirements, implicit requirements are added automatically by TeamCity based on build step configuration. However, these requirements focus exclusively on parameter references.

For example, if a configuration has the echo "%myParam%" command-line build step, it is implied the myParam parameter exists and has value. Otherwise, if a parameter is missing or empty, there is nothing to print out. In this case, TeamCity shows a corresponding warning on the Parameters tab...

...and displays a corresponding entry on the Agent Requirements tab.

In other words, an implicit requirement can be interpreted as "a configuration uses an unknown parameter" warning. To resolve this issue, you need to either provide a parameter value on a configuration/project level, or define this parameter inside a build agent buildAgent.properties file.

## TeamCity build agent configuration file

######################################
#   Required Agent Properties        #
######################################

<...>

myParam="Hello world"

If at least one agent reports this parameter, it will be listed as compatible and the implicit requirement will be hidden from the Agent Requirements tab.

Along with configuration-wide requirements, you can define requirements to agents for individual build steps. To do so, open step settings and add a parametrized execution condition.

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.