|You are viewing documentation of TeamCity 5.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.|
This page describes how plugins should be packaged by plugin developers. See Installing Additional Plugins for instruction on plugin installation.
To write TeamCity plugin it is beneficial to have some knowledge about Spring Framework. Server-side and agent-side TeamCity plugins are initialized via Spring container. This means that every plugin should have a Spring bean definition file describing main plugin services.
There is a convention how bean definition file should be named:
where an asterisk can be replaced with any text, for example: build-server-plugin-cvs.xml. Bean definition files should be placed into the META-INF folder of the JAR archive containing plugin classes.
TeamCity is able to load plugin from the following directories:
You can put plugin into plugins directory as a separate folder or as a zip archive. Note that server must be restarted to load your plugin.
If you use a separate folder:
If you use a zip file:
Inside plugin directory there should be the following structure:
agent directory must contain one file only: <agent plugin zip> which should be prepared so that all files and directories are placed into the single root directory. That is, there must be one root folder in the archive (<plugin top level directory> in the diagram below), and there should not be other files at the top level. Usually for convenience the name of <plugin top level directory> is the same as the plugin name. All jar files required by the plugin on the agent must be placed to the lib subfolder:
server folder contains server side part of the plugin, that is, a bunch of jar files.
teamcity-plugin.xml contains some meta information about plugin, like its name and version, see below.
On the agent side all plugins and their libraries are always loaded by shared classloader.
On the server side by default plugins are loaded in the shared classloader too, however it is possible to load plugin in separate classloader by specifying special parameters in the teamcity-plugin.xml file.
When server starts it places all agent plugins into the <TeamCity home>/webapps/ROOT/update/plugins folder. After that if content of the folder has changed, agents will receive upgrade command from the server and download updated files automatically. Note that server tracks changes in this folder and can initiate agent upgrade procedure on the fly. In practice it means that if you want to deploy updated agent part of your plugin without server restart you can put your agent plugin to this folder.
After successful upgrade your plugin will be unpacked into the <Agent home>/plugins/ folder. Note that if agent is busy running build it won't upgrade until the build finishes. Also no new builds will start on the agent if it should be updated.
teamcity-plugin.xml file should be placed to the root of plugin folder. You can refer to XSD schema for this file which is unpacked to <TeamCity data directory>/config/teamcity-plugin-descriptor.xsd
An example of teamcity-plugin.xml:
Starting from TeamCity 5.0 it is allowed to define plugin parameters in the teamcity-plugin.xml file:
Plugin parameters can be accessed from jetbrains.buildServer.web.openapi.PluginDescriptor#getParameterValue(String) method.