To write a TeamCity plugin, the knowledge of Spring Framework is beneficial.
There are server-side and agent-side plugins in TeamCity. Server-side and agent-side plugins are initialized in their own Spring containers; this means that every plugin needs a Spring bean definition file describing the main services of the plugin. Bean definition files are to be placed into the
META-INF folder of the JAR archive containing the plugin classes.
There is a convention for naming the definition file:
build-server-plugin-<plugin name>*.xml — for server-side plugins
build-agent-plugin-<plugin name>*.xml — for agent-side plugins, where the asterisk can be replaced with any text, for example: build-server-plugin-cvs.xml.
TeamCity is able to load plugin from the following directories:
<TeamCity data directory>/plugins— user-installed plugins
<TeamCity web application>/WEB-INF/plugins— default directory for bundled TeamCity pluginsPlugins with the same name (for example, a newer version) located in
<TeamCity data directory>/pluginswill override the plugins in the
<TeamCity web application>/WEB-INF/pluginsdirectory.
TeamCity creates a child Spring Framework context per plugin. There are two options to load plugins classes: standalone and shared:
Standalone classloading (recommeneded) allows loading every plugin to a separate classloader. This approach allows a plugin to have additional libraries without the risk of affecting the server or other plugins.
Shared classloading allows loading all plugins into same classloader. It is not allowed to override any libraries here.You may specify desired the classloading mode in the
teamcity-plugin.xmlfile, see the section below.
The TeamCity plugin loader supports plugin dependencies, described below.
A server-side plugin may affect the server only, or may include a number of agent-side plugins that will be automatically distributed to all build agents.
A plugin can be a zip archive (recommended) or a separate folder.
If you use a zip file:
TeamCity will use the name of the zip file as the plugin name
If you use a separate folder:
TeamCity will use the folder name as the plugin name
The plugin zip archive/directory includes:
<agent plugin zip>if your plugin affects agents too, see the section below.
teamcity-plugin.xmlcontaining meta information about the plugin, like its name and version, see the section below.
serverdirectory containing the server-side part of the plugin, i.e, a number of jar files.
The plugin directory should have the following structure:
The server-only plugin:
The plugin affecting the server and agents:
Web Resources Packaging
In most cases a plugin is just a number of classes packed into a JAR file.
buildServerResources subfolder of the plugin's .jar file. Upon the server startup, these files will be extracted from the archive. You may use
jetbrains.buildServer.web.openapi.PluginDescriptor spring bean to get the paths to the extracted resources (read more on how to construct paths to your JSP files).
It is a good practice to put all resources into a separate .jar file.
teamcity-plugin.xml file must be located in the root of the plugin directory or .zip file. You can refer to the XSD schema for this file which is unpacked to
<TeamCity data directory>/config/teamcity-plugin-descriptor.xsd
An example of teamcity-plugin.xml:
It is recommended to set the
use-separate-classloader="true" parameter to
true for server-side plugins. To reload the plugin without the server restart, use the
allow-runtime-reload="true" parameter for deployment.
The plugin parameters can be accessed via the
TeamCity build agents support the following plugin structures:
new plugins (with the
teamcity-plugin.xmldescriptor), including tool plugins * tool plugins (with the
teamcity-plugin.xmldescriptor). This is a kind of plugin without any classes loaded into the runtime. Tool plugins for agents are used to only distribute binary files to agents, e.g. the NuGet plugin for TeamCity creates a tool plugin for agents to redistribute the downloaded NuGet.exe to TeamCity agents. See more at Installing Agent Tools.
deprecated plugins (with the plugin name folder in the .zip file)
agent directory must have one file only: <agent plugin zip> structured the following way:
Deprecated Plugin Structure
The old plugin structure implied that all plugin files and directories were placed into the single root directory, i.e. there had to be one root directory in the archive, the <plugin name directory>, and no other files at the top level. All .jar files required by the plugin on agents were placed into the
There must be no other items in the root of .zip but the directory with the plugin name. TeamCity build agent detects and loads such plugins using the shared classloader.
Now a new, more flexible schema of packing is recommended. The plugin name root directory inside the plugin archive is no longer required. The agent plugin name now is obtained from the
PluginName.zip file name. The archive needs to include the plugin descriptor,
teamcity-plugin.xml, see below.
It is required to have the
teamcity-plugin.xml file under the root of the agent plugin
.zip file. The agent tries to validate the plugin-provided
teamcity-plugin.xml file against the xml schema. If
teamcity-plugin.xml is not valid, the plugin will be loaded, but some data from the descriptor may be lost.
teamcity-plugin.xml file provides the plugin description (same as it is done on the server-side):
To deploy a tool, use the following
Making File Executable
There is experimental ability (can be removed in the future versions!) to set executable bit to some files after unpacking on the agent. Watch TW-21673 for proper solution. To make some files of a tool executable, use the following
<include name='path_to_a_file' /> relative to your tool folder (e.g.
<Agent home>/tools/<your tool name>) specifies the list of files to be made executable on Linux/Unix/Mac. Note that wildcards are not supported.
See Installing Agent Tools for installation instructions.
Plugin dependencies are present on both the server and agent side: some components are separated from the core into separate bundled plugins: Ant runner, IDEA runner, .NET runners, JUnit, and TestNG support. If you need some functionality of one of these plugins, use the plugin dependencies feature.
To use plugin dependencies, add the `dependencies` tag into the plugin xml descriptor:
Example of the server-side plugin descriptor using plugin dependencies:
Example of agent-side plugin descriptor:
The names of the bundled tools and plugins are just the names of the corresponding folders in
<TeamCity Home>/webapps/ROOT/WEB-INF/plugins for the server-side plugins and
<Agent home>/plugins/ or
<Agent home>/tools/ for the agent-side plugins and tools.
Agent Upgrade on Updating Plugins
TeamCity server monitors all agent plugins .zip files for a change (plugin files changed, added or removed). Once a change is detected, agents receive the upgrade command from the server and download the updated files automatically. It means that if you want to deploy an updated agent part of your plugin without the server restart, you can put your agent plugin into this folder.
After a successful upgrade, your plugin will be unpacked into the
<Agent home>/plugins/ or
<Agent home>/tools/ folders. Note that if an agent is busy running a build, it will upgrade only after the build finishes. No new builds will start on the agent if it is to be upgraded.