Agent Requirements
Agent requirements are defined on the Agent Requirements tab of the Stage Options dialog.
These are a set of rules that determine which agents are eligible to run a stage. All rules must evaluate to true for an agent to be selected for the stage. See Expression Objects for details of the types of expressions that can be used in these rules.
For example, you might:
- exclude a particular agent with the hostname "agent-x" by adding the rule
[$Agent.Hostname$] [Does not Equal] [agent-x], - select an agent based on a variable by using the rule
[$Agent.Hostname$] [Equals] [%DeployToAgentHostName%], or - require that version 9.0.4 of ASPNetCore is installed on the agent with the rule
[$Agent.AspNetCore.App.9.0.4.Path$] [Exists].
Prioritising Agent Selection
In addition to defining requirement rules, you can also configure how agents are prioritised when multiple agents are available that meet the requirements.
You can specify an expression in the Agent Priority field to determine which agent should be selected first. The expression typically refers to a property that varies between agents.
Agent Priority Expression
By default, this value is: $Agent.Priority.Value$, the value for which can be specified in the Agent Properties list.
How Agent Selection Works
When choosing among eligible agents:
The default behaviour is to select the agent with the highest capacity, calculated by subtracting the number of running stages from the concurrent stage limit:
Capacity = Concurrent Stage Limit - Number of Running StagesIf multiple agents have the same capacity, the one with the highest priority value (based on the priority expression) is selected. Priority values are compared numerically or alphabetically.
Reversing Priority
You can reverse the priority order by ticking the Select agent in reverse order of priority checkbox.
Overriding Capacity with Priority
If the Priority overrides capacity option is enabled:
- The agent with the highest priority value is selected first, even if other agents have more capacity.
- If multiple agents share the same priority value, the one with the highest capacity is chosen.
Agent Prioritisation
| Scenario | What Happens |
|---|---|
| Multiple agents meet all requirements | System compares their capacity first. |
| Agents have different capacities | Agent with highest capacity is selected. |
| Agents have same capacity | Agent with highest priority value (as per expression) is selected. |
| "Reverse order of priority" is ticked | Agent with lowest priority value is preferred. |
| "Priority overrides capacity" is enabled | Agent with highest priority value is selected first, ignoring capacity. |
| Equal priority values when overridden | Agent with highest capacity is used as tiebreaker. |