Plugins Packaging

This page is intended for plugin developers and explains how to package TeamCity plugins and agent tools. See Installing Additional Plugins and Installing Agent Tools for installation instructions.

On this page:

Introduction

To write a TeamCity plugin, the knowledge of Spring Framework is beneficial.

There are Plugin Types in TeamCity 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.

Plugins Location

TeamCity is able to load plugin from the following directories:

<TeamCity data directory> /plugins – Installing Additional Plugins plugins
< TeamCity web application >/WEB-INF/plugins — default directory for bundled TeamCity plugins

Plugins with the same name (for example, a newer version) located in < TeamCity data directory >/plugins will override the plugins in the < TeamCity web application >/WEB-INF/plugins directory.

Plugins Loading

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.xml file, see the Plugin-Descriptor.

Server-Side Plugins

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.

Plugin Structure

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
The plugin zip file will be automatically unpacked to a temporary directory on the server start-up

If you use a separate folder:

TeamCity will use the folder name as the plugin name

The plugin zip archive/directory includes:

teamcity-plugin.xml containing meta information about the plugin, like its name and version, see the Plugin-Descriptor.
the server directory containing the server-side part of the plugin, i.e, a number of jar files.
the agent directory containing <agent plugin zip> if your plugin affects agents too, see the agentDirectory.

The plugin directory should have the following structure:

The server-only plugin:

server | --> <server plugin jar files> teamcity-plugin.xml

The plugin affecting the server and agents:

agent | --> <agent plugin zip files> (see [below|#agentDirectory]) server | --> <server plugin jar files> teamcity-plugin.xml

Web resources packaging

In most cases a plugin is just a number of classes packed into a JAR file.

If you wish to write a custom page for TeamCity, most likely you'll need to place images, CSS, JavaScript, JSP files or binaries somewhere. The files that you want to access via hyperlinks and JSP pages are to be placed into the 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 (Web UI Extensions on how to construct paths to your JSP files).

It is a good practice to put all resources into a separate.jar file.

Plugin Descriptor

The teamcity-plugin.xml file must be located in the root of the plugin dicrectory 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:

<?xml version="1.0" encoding="UTF-8"?> <teamcity-plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:shemas-jetbrains-com:teamcity-plugin-v1-xml"> <info> <name>PluginName</name>  <display-name>This name may be used for UI</display-name> <description>Some description goes here</description> <version>0.239.42</version> </info> <deployment use-separate-classloader="true" />  <parameters> <parameter name="key">value</parameter>  </parameters> </teamcity-plugin>

(!)It is recommended to set the use-separate-classloader="true" parameter to true for server-side plugins.

The plugin parameters can be accessed via the jetbrains.buildServer.web.openapi.PluginDescriptor#getParameterValue(String) method.

Agent-Side Plugins

TeamCity build agents support the following plugin structures:

new plugins (with the teamcity-plugin.xml descriptor), including tool plugins
- tool plugins (with the teamcity-plugin.xml descriptor). 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)

Plugin Structure

The 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 lib subfolder:

<plugin name directory> | --> lib | --> <jar files>

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.

New Plugins

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, Plugin-Descriptor.

agent-plugin-name.zip | - teamcity-plugin.xml - lib | plugin.jar plugin.lib

Plugin Descriptor

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.

Plugins

This teamcity-plugin.xml file provides the plugin description (same as it is done on the server-side):

<?xml version="1.0" encoding="UTF-8"?> <teamcity-agent-plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:shemas-jetbrains-com:teamcity-agent-plugin-v1-xml"> <plugin-deployment use-separate-classloader="true"/> </teamcity-agent-plugin>

Tools

To deploy a tool, use the following teamcity-plugin.xml file:

To make some files of a tool executable, use the following teamcity-plugin.xml file:

<?xml version="1.0" encoding="UTF-8"?> <teamcity-agent-plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:shemas-jetbrains-com:teamcity-agent-plugin-v1-xml"> <tool-deployment> <layout> <executable-files> <include name='path_to_a_file'/> </executable-files> </layout> </tool-deployment> </teamcity-agent-plugin>

where <include name='path_to_a_file' /> specifies the list of files (relative to agent plugin directory) to be made executable on Linux/Unix/Mac. See Installing Agent Tools for installation instructions.

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.

Last modified: 20 April 2023