Plugins Packaging

TeamCity is able to load plugin from the following directories:

• <TeamCity data directory> /plugins

• <teamcity server root>/webapps/ROOT/WEB-INF/plugins — default directory for bundled TeamCity plugins

This section contains short reference on general aspects of plugins packaging:

Plugins Directory Structure

You can put plugin into plugins directory as a separate folder or as a zip archive.

If you use a separate folder:

• TeamCity will use the folder name as plugin name

• Plugin name has to be unique

• Plugin folder:

  • all .jar files in the root folder and under 'server' folder are taken as server-side plugin .jar files.

  • all .zip or .jar files under 'agent' folder are taken as build agent plugins. These files should be packed as described on the Agent-Side Extensions page

If you use a zip file:

• TeamCity will use name of the zip file as the plugin name

• Plugin zip file will be automatically unpacked on server startup to directory with the same name

Plugin Web Resources

• In your plugin jar file create buildServerResources and place there all web resources.

• TeamCity looks for plugin's web resources in the <plugin name>.jar/buildServerResources folder.

• All found resources are unpacked to web-visible folder.

• Folder path can be retrieved by calling jetbrains.buildServer.web.openapi.PluginDescriptor#getPluginResourcesPath() method.

• In JSP file ${teamcityPluginResourcesPath} attribute is provided with path to plugin web resources.

Plugin Loading

• Each plugin is loaded to separate spring framework context

• All plugin's classes are loaded using one shared plugins classloader or separate plugin classloader depending on the xml setting. Plugins shared classloader is used by default.

• TeamCity registers JspServlet to run all plugin's .jsp files.

• TeamCity registers agent side plugins

• All plugin resources are unpacked to web-visible path.

• PluginDescriptor class is registered for plugin's spring context.

Api

• All plugin classes may require jetbrains.buildServer.web.openapi.PluginDescriptor class from spring application context. That class provides the name of plugin on the server, web resource path to all plugin's resources.

• Interface jetbrains.buildServer.web.openapi.WebResourceManager is obsolete now.

Plugin XML Descriptor

• XSD schema for the XML is unpacked to <teamcity data directory>/config/teamcity-plugin-descriptor.xsd

• This file should be placed to the root of plugin folder.

• XML file should be named teamcity-plugin.xml

Sample minimal teamcity-plugin.xml:

XML Parameters

• teamcity-plugin/deployment/@use-separate-classloader — this parameter changes classloader to be used for loading plugin's classes on the server. This parameter can possess the following values:

  • true — use separate classloader

  • false — load classes using shared plugins' classloader

By default plugin's classes are loaded to the shared plugins' classloader. For example:

... <deployment use-separate-classloader="true" /> ...

• teamcity-plugin/info/name element allows to override plugin name. By default TeamCity uses plugin folder name or plugin file name.