TeamCity is a highly extendable system. You can add various plugins in different places, including, but not limited to:
- Custom notifiers
- Custom build triggers
- Custom build runners with possibility to view customized reports on the Web
- Extensions to Ant Runner which allows to add custom logging and view reports on the Web
- Custom statictics reports based on the information in the database
- Custom user authentication
- Support of additional VCS
Some of the TeamCity extensions require only server-side plugin, other may require build agent plugin.
The OpenAPI sources of the TeamCity is placed to the root directory of full TeamCity distribution under the name
Server-side plugin organization and deployment
To write a server-side plugin, you'll need to include jar libraries from TeamCity/webapps/ROOT/WEB-INF/lib directory to your classpath.
Server-side plugins are delivered as a set of jar files, one of which contains the plugin descriptor file.
Such plugins can process data which is logged from build agents in some specific way, provide additional web content, create custom notifiers, etc.
The plugin code should be active - plugin components should register themselves in various TeamCity managers and components. Corresponding TeamCity managers should be passed via constructor (they will be passed by Spring framework via autowiring, see Descriptor section below)
The plugin descriptor file is named build-server-plugin-<unique_plugin_name>.xml and contains component definitions according to Spring configuration file syntax.
Base configuration of the server can be found in /WEB-INF/buildServerSpring.xml file.
Put the jar files with server side plugins into the /WEB-INF/lib/ directory on the server.
How to write server-side extensions
Build server listeners
Should extend jetbrains.buildServer.serverSide.BuildServerListener interface and register itself using
SBuildServer.addListener() method. There is convinient jetbrains.buildServer.serverSide.BuildServerAdapter class.
Server-side extension points
TeamCity server has a number of extension points, where a plugin can provide some additional functionality. An extension point is defined in terms of interface, which extends jetbrains.buildServer.serverSide.ServerExtension. There are several such interfaces/extension points. To register an extension, plugin should invoke method jetbrains.buildServer.serverSide.SBuildServer#registerExtension(extension_class, pluginCode, extensionObject).
Here is a list of some extension points (some of them are available only in TeamCity 3.0/Benares):
- jetbrains.buildServer.serverSide.ParametersPreprocessor allows to modify build and run parameters which are sent to TeamCity server
- jetbrains.buildServer.serverSide.DataCleaner allows to register additional cleanupers for the case when build is removed
- jetbrains.buildServer.serverSide.GeneralDataCleaner allows to register global additional cleanup procedures which are called once per cleanup
- jetbrains.buildServer.serverSide.MainConfigProcessor allows to read/write global TeamCity data, which are saved in XML file main-config.xml
- jetbrains.buildServer.serverSide.TextStatusBuilder allows to modify build status description line, like Tests passed: 343, Fitnesse: 23
Web resources (jsp, css, js, etc) should be placed into the plugin jar file under the path buildServerResources/. After that you should register this jar in the WebResourcesManager. This should be done while Spring is creating objects (i.e. in the plugin constructor). For example:
Plugin jar should be placed into the /WEB-INF/lib/ directory. Resources like buildServerResources/file.js will be unpacked under the name /plugins/aPluginName/file.js. You can obtain this path with help of WebResourcesManager.resourcePath() method.
If custom VCS plugin requires some settings to be edited from the web UI then it should also provide a JSP file for its settings. This JSP file should be placed into the plugin jar under the path buildServerResources/. In the buildServerSpring.xml you should also configure webResourcesUnpacker (note that you should use your vcs name as a plugin name), see above.
In the JSP file you should use special custom tags for input fields, radio buttons and checkboxes that correspond to you VCS properties. These custom tags are located in the props tag library:
You can use JSP files of existing VCS plugins as an example.
Custom template processing:
View build log tabs
Implement interface ViewLogTab and add the implementation to the build server using call
Custom user authentication
Custom authentication API is based on Sun JAAS API. To provide your own authentication scheme you should provide login module class which must implement interface javax.security.auth.spi.LoginModule and register it in the jetbrains.buildServer.serverSide.auth.LoginConfiguration.
Now we should register this module in the server. For this we create login module descriptor:
Finally we should create build-server-plugin-ourUserAuth.xml as it is described above and write there CustomLoginModuleDescriptor bean:
Create jar, put it into the WEB-INF/lib directory of the TeamCity server and restart it. When server started you should be able to choose your custom plugin from the drop down on the Administration -> Server Configuration page.
Build Agent plugins
Currently, there are two ways to extend build agent:
- Write a custom build runner
- Write an extension to AntRunner (for instance, to process custom tasks)
Both ways use similar way of plugin packaging and deployment (see below).
Plugin descriptor for the build agent plugins is named build-agent-plugin.xml. A build agent reads its plugins using
Package your build agent plugin as a zip archive with the following content:
This archive will be unpackaged in the plugins subdirectory during the build agent installation:
Writing custom build runner
Implement jetbrains.buildServer.agent.BuildRunner interface (you may also extend GenericProgramRunner or even JavaProgramRunner helpers for this). To log your messages you may obtain instance of ServerLogger singleton (you may also use ServerLoggerFacade for convinience).
Build agent plugin should also provide server side jar with a class implementing jetbrains.buildServer.serverSide.RunType interface. The implementation of the RunType interface must be registered in the jetbrains.buildServer.serverSide.RunTypeRegistry. You can do this in the constructor of the RunType implementation, like this:
Please note that you should also provide the plugin descriptor file named build-server-plugin-<unique_plugin_name>.xml which will contain reference to the RunType implementation:
Writing ant extension
Implement jetbrains.buildServer.agent.ant.AntTaskExtension interface and register it as a component in
To deploy a build agent plugin, copy its zip archive to the /WEB-INF/update/plugins directory on the Team Server. Server part of the plugin must be copied into the WEB-INF/lib directory of the Tomcat server. If server part was modified, you should also restart Tomcat server. Agents will download updated plugin automatically.