TeamCity Cloud 2023.09 Help

Agent Requirements

Agent requirements are special conditions that define whether a build configuration can run on a particular build agent. Together with grouping by agent pools, they give you a flexible control over how builds are distributed to agents.

To create an explicit agent requirement for a given build configuration, go to Build Configuration Settings | Agent Requirements and click Add new requirement. Each requirement represents a conditional rule for a certain parameter. While you are entering a parameter name or value, TeamCity will show you related suggestions.

To temporarily disable or delete a requirement, use its context menu.

Agent Requirements Based on Environment Variables and Properties

When a build agent registers on the TeamCity server, it provides information about its configuration, including its environment variables, system properties, and additional settings specified in the buildAgent.properties file. You can use these parameters to define agent requirements.

For example, if the current build configuration must run only on a Windows agent, add the following rule:

  • Parameter name: teamcity.agent.jvm.os.name

  • Condition: equals

  • Value: Windows

After this requirement is created, TeamCity will check the value of the jvm.os.name system property on all active agents. If it does not equal Windows on a particular agent, this agent will be marked as incompatible with the current build configuration.

You can also use regular expressions to match parameter values. For example, if you want to select the agent by matching various parts of the agent name, add the following rule:

  • Parameter name: teamcity.agent.name

  • Condition: matches

  • Value: (macos|linux|win)-(m|l|xl).*

Both compatible and incompatible agents are listed in Build Configuration Settings | Agent Requirements.

You can add multiple agent requirements for a single parameter. The agent will be considered compatible only if it satisfies all these requirements.

Implicit Requirements

Any reference (a name enclosed in % characters) to an unknown parameter within a build is considered an implicit requirement. The build will only run on an agent if:

  • The agent provides this parameter, or

  • The parameter is defined on the build configuration (or project) level.

The priority of the build configuration's value is higher than of the value defined on the agent.

For example, if you define a build runner parameter as a reference to another property: %env.JDK_16%/lib/*.jar, this will implicitly add an agent requirement for the referenced property: that is, env.JDK_16 must be defined. To define such properties on the agent, you can:

  • Specify them in the buildAgent.properties file.

  • Set the environment variable JDK_16 on the build agent.

  • Specify the value on the Parameters page of a build configuration (or in the Project Settings). The same value of the property will be used for all build agents.

Agent Requirements Video Guide

Last modified: 12 September 2023