Build Agent
A TeamCity build agent is a piece of software which listens for the commands from the TeamCity server and starts the actual build processes. There are two types of agents in TeamCity Cloud: JetBrains-hosted and self-hosted. The first ones are maintained and configured by JetBrains. They are started on-demand as soon as each new build requires to be run. The second ones are stored and configured by the customer. Both types of agents can be successfully combined in one TeamCity Cloud installation. Please see Subscription and Licensing on details between these agents in terms of the TeamCity Cloud subscription.
A TeamCity build agent contains two processes:
Agent launcher — a Java process that launches the agent process.
Agent — the main process for a build agent; runs as a child process for the agent launcher.
An agent typically checks out the source code, downloads artifacts of other builds and runs the build process. An agent can run a single build at a time. The number of agents basically limits the number of parallel builds and environments in which your build processes are run.
An agent can run builds of any compatible build configuration.
The TeamCity server monitors all the connected agents and assigns queued builds to the agents based on compatibility requirements, agent pools, build configuration restrictions configured for an agent and the selection algorithm described here.
Build Agent Status
In TeamCity, a build agent can have following statuses:
Status | Description |
|---|---|
Connected/ Disconnected | An agent is connected if it is registered on the TeamCity server and responds to server commands, otherwise it is disconnected. This status is determined automatically. |
Authorized/ Unauthorized | Agents are manually authorized via the web UI on the Agents page. Only authorized build agents can run builds. The number of authorized agents at any given time cannot exceed the number of agent licenses entered on the server. When an agent is unauthorized, a license is freed and a different build agent can be authorized. Purchase additional licenses to expand the number of agents that can concurrently run builds. When a new agent is registered on the server for the first time, it is unauthorized by default and requires manual authorization to run the builds. If a build agent is installed and running on the same computer as the TeamCity build server, it is authorized automatically. |
Enabled/ Disabled (Disabled for maintenance for cloud agents) | Agents are manually enabled/disabled via the web UI. The TeamCity server only distributes builds to agents that are enabled. Agent disabling does not affect (stop) the build which is currently running on the agent. Disabled agents can still run builds when the build is assigned to a special agent (for example, by triggering a custom build). This feature is generally used to temporarily remove agents from the build grid to investigate agent-specific issues. |
All agents connected to the server must have unique agent names.
Only users with certain roles can manage agents. See this article for more information.
For a build agent configuration, refer to this section.
Agent Upgrade
Both JetBrains-hosted and self-hosted agents upgrade automatically when the server is upgraded. Note that receiving new files following the server upgrade may trigger an agent restart for the changes to take effect. If your self-hosted agents run under user accounts with sufficient permissions, all restarts happen automatically and do not require your input.
Agent Priority
If you have a mix of JetBrains-hosted and self-hosted agents, TeamCity uses the following set of rules to pick an optimal agent that is the most balanced in terms of both performance and price:
Self-hosted agents have priority over JetBrains-hosted agents
Per-month agents have priority over per-minute agents
If agents on any platform can run a build, TeamCity prioritizes Linux agents first, then Windows, and lastly, macOS.
Priorities of AWS-hosted agents depend on their instance types. Smaller agents have priority over larger ones.
Agents with the latest OS versions have priority over agents with older versions.
Agents installed on x86_64 machines have priority over ARM agents.
You can manually lower or raise the priority of a self-hosted agent by modifying its integer teamcity.agent.priority property. This property accepts values in the -10000 ~ 10000 range with the default value of 0. For EC2 build agents, you can set this property on the Cloud Image settings page:
For other cloud images and bare-metal agents, add the following line to the <TeamCity_Agent_Home>/conf/buildAgent.properties file: