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:
Navigate to Administration | <Your Configuration> to access build configuration settings.
Open the Agent Requirements settings tab.
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.
tip
You can also set requirements to agents in the scope of each build step.
In a step's settings, add a parametrized execution condition that defines a requirement to build agents. This way, this step will be executed during a build run only if the current agent satisfies this condition.
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.
tip
If you are not sure why a certain requirement is not met, contact a responsible project or system administrator who created this requirement.
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.
Thanks for your feedback!