TeamCity Integration with IntelliJ-based IDEs
Starting from its very first version, TeamCity has provided support for IntelliJ platform-based IDEs; and since they are products from JetBrains, this integration is the most powerful one when compared to other IDE integrations.
The main idea behind the integration is the ability to take advantage of all the features provided by TeamCity as a continuous integration server without leaving the context of the IDE: using the integration, you can configure notifications, run builds and tests, get the build status, view your changes, assign investigations and perform other actions available in TeamCity right from the IntelliJ IDEA. Besides, the integration allows cross navigation between the IDE and build results in TeamCity; for non-DVCS it allows you to test your local changes and see how they integrate with the source code before the commit, which ensures your changes do not break anything.
In this blog post we’ll go over the setup of the TeamCity plugin with IntelliJ IDEA.
TeamCity provides the same level of support for both IntelliJ IDEA editions: the free community edition and the paid ultimate edition. All the IntelliJ platform-based IDEs are also supported: JetBrains RubyMine, JetBrains PyCharm, JetBrains PhpStorm/WebStorm, and AppCode. The versions compatibility information is provided in the TeamCity documentation.
So, first we need to install the TeamCity plugin.
Installing the Plugin
There are two ways to install a plugin.
Installing from the plugins repository
You can install the plugin right from the IDE (connection to the Internet is required) using File | Settings | Plugins. Click Browse JetBrains Plugins and search for TeamCity Integration. Double-click on the listed plugin to download and install it.
Alternatively, you can download the plugin directly from the TeamCity server, which is especially useful if the Internet access is restricted in your organization.
Installing from the TeamCity server
Log in to the TeamCity server, in the right top corner, click the arrow next to your username and select My Settings & Tools on the right of your name. On the right, you will see TeamCity Tools.
- Click on the download link near IntelliJ Platform plugin and download TeamCity-IDEAplugin.zip to your local machine.
- After this, in IDEA, go to File | Settings | Plugins | Install plugin from disk… and in the explorer window, select the downloaded ZIP archive.
- Click OK.
Next we’ll restart the IDE is required to activate the plugin.
Logging in to TeamCity
To log in to the TeamCity server, click TeamCity | Log in… and provide the required credentials:
After you log in, if you installed the plugin from the IDE, you might have to update the plugin to the version corresponding to the TeamCity server you are connected to using the TeamCity | Update plugin menu item.
Now let’s see the integration in action.
Next we’ll configure notifications which the TeamCity server will send to our IDE. This can be done using TeamCity | Options | Edit Notification Rules or by clicking a link in the TeamCity tool window asking you the specify the projects you want to watch: either of the options redirects you to the Notification Rules page in the Web UI of the TeamCity server you are connected to. By default, TeamCity sends out IDE notifications to the user if a build containing their changes fails. You can add your own rules here:
TeamCity will track the changes by the username specified in the VCS Usernames section.
Open Files from TeamCity in IDE
When looking at changes in the TeamCity Web UI, you can open changed files from in the IDE:
Clicking the IDE link opens up the specific file in the active IDE, i.e. the IDE we are currently connected to.
You can also work with all changes: in this case the patches are downloaded to the IDE, and they can be applied to the working directory as required.
Working with TeamCity from IDE
At the bottom on the left the TeamCity tool window has the Projects, My Changes, and My Investigations tabs, which correspond to the options available in the TeamCity Web UI.
The Projects tab displays projects and build configurations we decided to monitor. It also allows us to configure more visible projects by redirecting us to the TeamCity Web UI.
Let’s run a build from the IDE: right-clicking the build configuration name (Build in the image below) opens a menu allowing you to add a build to the queue, view pending changes, assign and investigation to any user registered on the TeamCity server you are connected to, mark an investigation as fixed, open the build configuration home page in the browser.
The My Changes tab displays all changes made by you and detected by TeamCity according to the specified username:
You can filter the changes and see only those related to the project you are currently working on:
It is easy to see the details of a specific commit in the IDE or quickly open the TeamCity change details page in the browser by right-clicking on the change and selecting the required option:
If you are assigned to investigate problems (typically build failures caused by your changes) in TeamCity, you will your investigations in the My Investigations tab.
As you can see, the TeamCity plugin enables you to run builds, view change details, assign investigations and perform other actions available in TeamCity without leaving IntelliJ IDEA.
Committing Pre-Tested Changes to Non-DVCS
In our project we are using the most popular version control at the moment – Git, and we use Git branches to test how our changes integrate with the existing code. In this part we’ll talk about the feature that can help if your project uses centralized version controls (like Subversion (SVN) or Perforce).
Using the pre-tested commit feature, you can prevent committing defective code into a build, so the entire team’s process is not affected. First the developer runs a build in TeamCity with the local changes on the developer’s machine and if this remote run is successful, the changes are committed to the version control automatically.
“Remote” means that the build will not run on the developer machine, but on a TeamCity build agent and this build will include the changes on our developer’s machine and the code in the version control: this way we can see how our changes integrate with other changes in the repository and be sure that our changes will not break the code.
If the remote run (also called ‘Personal Build’) fails, we will get a notification and can roll the changes back or fix the issues.
To trigger a remote run, we’ll use the TeamCity | Remote Run menu item. In the dialog that is displayed, select all changes you made locally or cherry-pick just the changes you want to test on the build server like we did. It is possible to select when to commit the changes: our changes will be committed if no builds fail. All whats left is to click the OK button and the remote run starts:
Debugging Java Code Remotely
We already mentioned that TeamCity integration supports all IntelliJ-based IDEs: it is programming language agnostic. However, some of its features are limited to a particular technology, and the next feature we’ll talk about is Java-specific.
The TeamCity plugin for IntelliJ IDEA allows you to debug your tests remotely on the TeamCity agent machine from the IDE on the local developer machine. The remote debug feature is useful if the agent environment is unique in some aspect, which causes a test to fail, and it is difficult to reproduce the problem locally.
You can use this feature if the following requirements are met:
- an IntelliJ IDEA run configuration (Java application run configuration /JUnit run configuration /JTestNG run configuration) on the local developer machine with the TeamCity plugin for IntelliJ IDEA is installed
- a build configuration on the TeamCity Server with the IntelliJ IDEA Project runner as one of the build steps
- a remote TeamCity agent to run this build available to the local machine by socket connection
To start debugging, select the TeamCity | Remote Debug menu item. You will be asked to select the run configuration to debug.
(Alternatively, you can right-click tests and select the Debug Remotely on TeamCity Agent option from the context menu.)
Now we click Debug Remotely on TeamCity agent. The build is added to the queue and the standard IntelliJ IDEA debug tool window appears.The debug tool window works in the listening mode, i.e. it waits for the agent to connect to it. Once the agent connects, the Java process on the agent is paused and the Agent Attached notification appears in the IDE. Now we can set some breakpoints, and actually start the debug session by clicking Start either in the notification popup or in the debug tool window.
When the build is finished, you can view failed tests in the IDE:
Once the JVM process exits, another notification popup appears in the IDE:
The debug session is not finished yet, it is possible to either repeat or finish it. Selecting Repeat will rerun the same build step again, which is much faster than starting a new debug session.
Well, we’ve covered some of the most popular features of the TeamCity-IDEA integration and really hope we managed to persuade you to try the integration.
Your feedback is most welcome as usual here in the comments or our issue tracker.
Happy integrating and building!