Assigning Build Configurations to Specific Build Agents

It is sometimes necessary to manage the Build Agents' workload more effectively. For example, if the time-consuming performance tests are run, the Build Agents with low hardware resources may slow down. As a result, more builds will enter the build queue, and the feedback loop can become longer than desired. To avoid such situation, you can:

Establish a run configuration policy for an agent, which defines the build configurations to run on this agent.
Define special Agent Requirements, to restrict the pool of agents, on which a build configuration can run the builds. These requirements are:
- Build Agent name. If the name of a build agent is made a requirement, the build configuration will run builds on this agent only.
- Build Agent property. If a certain property, for example, a capability to run builds of a certain configuration or an operating system, is made a requirement, the build configuration will run builds on the agents that meet this requirement.

Agent pools

You could split agents into pools. Each project could be associated to a number of pools. See Agent Pools.

Establishing a Run Configuration Policy

To establish a Build Agent's run configuration policy:

Click the Agents and select the desired build agent.
Click the Compatible Configurations tab.
Set the Current run configuration policy option to Run assigned configurations only.
Click the Assign configurations button and tick the desired build configurations names to run on the build agent.

Making Build Agent Name and Property a Build Configuration Requirement

To make a build configuration run the builds on a build agent with the specified name and properties:

Click Administration and select the desired build configuration.
Select the Agent Requirements tab in the left navigation panel (see Configuring Agent Requirements).
Click Add new requirement and enter "teamcity.agent.name" in the Parameter name field.
Change the condition to "equals" and enter the full agent name in the Value field.

The following Kotlin snippet illustrates the result:

object Build : BuildType({
   name = "Build"
   steps {
      // build steps
   }
   // ...
   requirements {
      equals("teamcity.agent.name", "SandboxBuilder14")
   }
})

Depending on your needs, you can modify this requirement as follows:

Change the Condition from "equals" to a non-strict operator (for example, "contains") to include multiple similarly named agents. For instance, the startsWith("teamcity.agent.name", "NightlyAgent") condition allows builds to run on "NightlyAgent1", "NightlyAgent_24", "NightlyAgent.A" and other build agents whose names satisfy the requirement.
Use the teamcity.agent.jvm.os.name parameter to choose agents by their operating systems rather than names. For example, equals("teamcity.agent.jvm.os.name", "Mac OS X").

Last modified: 25 April 2024