Build Agent
Last modified: 20 April 2023A TeamCity Build Agent is a piece of software which listens for the commands from the TeamCity server and starts the actual build processes. It is Setting up and Running Additional Build Agents separately from the TeamCity server. An agent can be installed on the same computer as the server or on a different machine (the latter is a preferred setup for server performance reasons).
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. 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 Agent Requirements, Agent Pools and Build Configuration restrictions configured for an agent.
If there are several idle agents that can run a build, TeamCity tries to select the fastest one based on the builds history.
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. |
Agents are manually authorized via the web UI on the Agents page. Only authorized build agents can run builds. The number of simultaneously authorized agents cannot exceed the number of agent licenses in your license pool. 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. | |
Agents are manually enabled/disabled via the Viewing Build Agent Details. 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 (e.g. 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 role and permission for more information.
For a build agent configuration, refer to the Build Agent Configuration section.
Agent Upgrade
A TeamCity agent is upgraded automatically when necessary. The process involves downloading new agent files from the TeamCity server and restarting the agent on the new files. In order to successfully accomplish this, the user under whose account the agent runs should have Setting up and Running Additional Build Agents permissions.
Typically, an agent upgrade happens when:
the server is Upgrade
an agent plugin is Plugins Packaging or Plugins Packaging on the server
Thanks for your feedback!