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.

  note

  The folder name is case-sensitive.

• 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.

  note

  None of mentioned classloaders in web application classloader.

• 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.