TeamCity Integration with IntelliJ-based IDEs

Julia Alexandrova

Starting from its very first version, TeamCity has provided support for IntelliJ platform-based IDEs. Because the IDEs are developed by JetBrains, this integration is the most powerful compared with other IDEs’ 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 lets you 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 IDEs based on the IntelliJ platform 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 the 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.

1. Click on the download link near the IntelliJ Platform plugin and download TeamCity-IDEAplugin.zip to your local machine.
2. After this, in IDEA, go to File | Settings | Plugins | Install plugin from disk… and in the explorer window, select the downloaded ZIP archive.
3. Click OK.

Next we’ll restart the IDE to activate the plugin.

After the restart, the TeamCity menu is available at the top of the screen.

At the bottom of the editor, on the left, the TeamCity tool window is now visible, and on the right we have the TeamCity ‘Logged out’ status icon.
Now we can connect to TeamCity.

Logging in to TeamCity

To log in to the TeamCity server, click TeamCity | Log in… and provide the required credentials:

If you installed the plugin from the IDE, after the login you might need 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.

Configuring Notifications

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 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 see your investigations on 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 existing code. In this part we’ll talk about the feature that can be helpful 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 system: 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 we’ll be able 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 what’s 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:

1. There’s 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 installed.
2. There’s a build configuration on the TeamCity Server with the IntelliJ IDEA Project runner as one of the build steps.
3. A remote TeamCity agent to run this build is 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, so 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 here in the comments or our issue tracker.

Happy integrating and building!

Subscribe to TeamCity Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!