You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

In TeamCity an agent tool (i.e. a set of files/a binary distribution) is a type of plugin without any classes loaded into the runtime; agent tools are used to only distribute binary files to agents.

TeamCity allows you to install additional tools on all the agents, which is especially useful in the environments with a large number of build agents as you can distribute tools to or remove them from all build agents at once, centralize configuration files distribution (e.g. you want to distribute a custom configuration file/library to all agents), etc.

The structure of the tool plugin is described on the Plugins Packaging page.

A tool to be distributed can be a separate folder or a .zip archive:

  • If you use a separate folder, TeamCity will use the folder name as the tool name on all agents.
  • If you use a zip file, TeamCity will use the name of the zip file as the tool name on all agents. The zip file will be automatically unpacked on the agents to the directory with the same name.

    Make sure the name of your tool is not the same as an existing TeamCity build agent tool: check the <Agent Home Directory>/tools folder for the TeamCity tools. A custom tool with the same name as an existing TeamCity build agent tool is ignored and will not be installed.

To distribute a set of files to all agents, perform the following:

  1. Create the .tools directory under <TeamCity Data Directory>/plugins.
  2. Under the .tools directory, create a directory or a .zip file containing the files you want to distribute to all the agents.
  3. TeamCity monitors the content of this folder so the tool will be automatically distributed to all agents and the files will appear in the <Agent Home Directory>/tools folder. No server restart is necessary. Agents will restart in the process of obtaining the tool.

You can see that the tool appears on the agent in the TeamCity Web UI by checking configuration parameters reported by the agent in the form teamcity.tool.<your tool name>.

You can use this parameter in your build: reference this parameter in the TeamCity Web UI (anywhere where the %parameter% format is supported) or refer to this parameters in your build as an environment or a system parameter.

To remove the previously installed tool from all agents, delete the .zip file or the folder with the tool from the <TeamCity Data Directory>/plugins/.tools directory. The tool will be removed from all agents.