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