The use of plugins allows you to extend the TeamCity functionality. See the list of existing TeamCity plugins created by JetBrains developers and community.
This document provides information on how to develop and publish a server-side plugin for TeamCity using Maven. The plugin will return the Hello World jsp page when using a specific URL to the TeamCity Web UI.
On this page:
- Step 1. Set up the environment
- Step 2. Generate a Maven project
- Step 3. Add information to your plugin descriptor
- Step 4. Create the plugin sources
- Step 4. Build your project with Maven
- Step 5. Install the plugin to TeamCity
- Next Steps
A plugin in TeamCity is a zip archive containing a number of classes packed into a JAR file and the plugin descriptor file.
Step 1. Set up the environment
To get started writing a plugin for TeamCity, set up the plugin development environment.
- Download and install TeamCity on your development machine. Since you are going to use this machine to test your plugin, it is recommended that this TeamCity server is of the same version as your production server. We are using TeamCity 9.0.2 installed on Windows in our setup.
- Download and install a Java IDE; we are using Intellij IDEA 14.0.3 Community Edition, which has a built-in Maven integration.
- Download and install Oracle Java. Set Java_Home on your system. We are using Java 1.7.
- Download and install Apache Maven. Set M2_HOME. Run
mvn -versionto verify your setup. We are using Maven 3.2.5. in our setup.
Step 2. Generate a Maven project
We'll generate a Maven project from an archetype residing in JetBrains Maven repository. Executing the following command will produce a project for a server-side-only plugin depending on 9.0 TeamCity version:
You will be asked to enter the Maven
packaging for your plugin.
We used the following values:
leave the default
demoPlugin will be used as the internal name of our plugin.
When the build finishes, you'll see that the
demoPlugin directory was created in the home directory of the current user.
View the project structure
The root of the
demoPlugin directory contains the following:
readme.txtfile with minimal instructions to develop a server-side plugin
pom.xmlfile which is your Project Object Model
teamcity-plugin.xmlfile which is your plugin descriptor containing meta information about the plugin.
demoPlugin-serverdirectory contains the plugin sources:
\src\main\java\zipcontains the AppServer.java file
src\main\resourcesincludes resources controlling the plugin look and feel.
build-server-plugin-demo-plugin.xml, the bean definition file for our plugin. TeamCity plugins are initialized in their own Spring containers and every plugin needs a Spring bean definition file describing the main services of the plugin.
builddirectory contains the xml files which define how the project output is aggregated into a single distributable archive.
Step 3. Add information to your plugin descriptor
teamcity-plugin.xml file in the project root folder and add the plugin display name and description by modifying the corresponding
attributes in the file. You can also specify additional information, such as the plugin author, email and etc.
Step 4. Create the plugin sources
pom.xml from the project root folder with Intellij IDEA.
We are going to make a controller class which will return
Hello.jsp via a specific TeamCity URL.
A. Create the plugin web-resources
The plugin web resources (files that are accessed via hyperlinks and JSP pages) are to be placed into the
buildServerResources subfolder of the plugin's resources.
- First we'll create the directory for our jsp: go to the
demoPlugin-server\src\main\resourcesdirectory in IDEA, right-click the folder, select New -> Directory and create the
- In the newly created
demoPlugin-server\src\main\resources\buildServerResourcesdirectory, right-click the folder, select New -> File and create the
B. Create the controller and obtain the path to the JSP
demoPlugin-server\src\main\java\zip and open the
AppServer.java file to create a custom controller:
- We'll create a simple controller which extends the TeamCity
class and implements
- The TeamCity open API provides the
jetbrains.buildServer.web.openapi.WebControllerManager which allows registering custom controllers using the path to them: the path is a part of URL starting with a slash
/appended to the URL of the server root.
- Next we need to construct the path to our JSP file. When a plugin is unpacked on the TeamCity server, the paths to its resources change. To obtain valid paths to the files after the plugin is installed, use the
jetbrains.buildServer.web.openapi.PluginDescriptor class which implements the
getPluginResourcesPathmethod; otherwise TeamCity might have difficulties finding our resources.
C. Update the Spring bean definition
Go to the
demoPlugin-server\src\main\resources\META-INF directory and update
build-server-plugin-demo-plugin.xml to include our AppServer class.
Step 4. Build your project with Maven
Go to the root directory of your project and run
target directory of the project root will contain the
<demoPlugin>.zip file. It is our plugin package, ready to be installed.
Step 5. Install the plugin to TeamCity
Copy the plugin zip to <TeamCity Data Directory>/plugins directory.
Restart the server and locate the TeamCity Demo Plugin in the Administration|Plugins List to verify the plugin was installed correctly.
The Hello World page is available via
<TeamCity server URL>/demoPlugin.html.