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.nameCondition:
equalsValue:
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.nameCondition:
matchesValue:
(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.propertiesfile.Set the environment variable
JDK_16on 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.