TeamCity 4.0 Help

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 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>XmlProvidedName</name> <!-- the name of plugin used in teamcity --> <display-name>This name may be used for UI</display-name> <version>0.239.42</version> </info> <deployment use-separate-classloader="true" /> <!-- load server plugin's classes in separate classloader--> </teamcity-plugin>

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.

Last modified: 20 April 2023