Teamscale Documentation
8.9

# Teamscale Integration with IntelliJ

Teamscale integrates with IntelliJ IDEA and many other IntelliJ IDEs, such as WebStorm and PyCharm.

Before installing the Teamscale Integration for IntelliJ, make sure its system requirements are met.

# Installing the Plug-in

Depending on your needs, there are several options to install the Teamscale Integration for IntelliJ.

For most users, installing the latest version of the plug-in from the Jetbrains Marketplace (opens new window) is recommended.

  1. Select File > Settings from the IDE's menu bar.
  2. Select Plugins.
  3. Search for Teamscale Integration in the Marketplace.
  4. Click the Install button.
  5. Restart the IDE to conclude the installation.

# Installing Any Version From the CQSE Website

Unlike the Jetbrains Marketplace, the CQSE website offers both the latest version and older versions of the plug-in.

  1. Select File > Settings from the IDE's menu bar.
  2. Select Plugins.
  3. Select Manage Plugin Repositories from the cogwheel menu.
  4. Add the desired plugin repository.
    • Latest Version: https://www.cqse.eu/download/teamscale/ide/intellij/latest/updatePlugins.xml
    • Older Version: https://www.cqse.eu/download/teamscale/ide/intellij/vM.N.x/updatePlugins.xml (replacing M.N by the feature version you need but keeping the .x, e.g., 7.8.x)
  5. Search for com.teamscale.ide.intellij.
  6. Click the Install button.
  7. Restart the IDE to conclude the installation.

# Installing While Offline

In case you cannot reach the Jetbrains Marketplace or CQSE Website during the installation, e.g., due to a security policy, you can perform an offline installation.

  1. Download an archive of the plugin repository from the CQSE website.
  2. Transfer the downloaded archive to your offline computer and unpack it there.
  3. Select File > Settings from the IDE's menu bar.
  4. Select Plugins.
  5. Select Install Plugin from Disk from the cogwheel menu.
  6. Select the com.teamscale.ide.intellij ZIP archive file inside the unpacked archive (not the plugin repository archive itself).
  7. Click the Install button.
  8. Restart the IDE to conclude the installation.

# Connecting to Teamscale

You need to perform the following actions to configure a Teamscale server:

  1. Open the IntelliJ settings via the menu File > Settings.

  2. Expand Tools (1) and select Teamscale (2) on the left hand side.

  3. Use the + button to add a new Teamscale server (3).

  4. In the details (4) fill in a descriptive Name for the server, its URL, and your Username and Access Key

    Configuring a Teamscale Server Connection

By clicking on the Get Key button, you can navigate to the Teamscale web interface and generate a personal access key.

Click the Validate Connection (5) button to ensure successful connection the Teamscale server. Click Apply and OK to save the settings.

# Configuring Using .teamscale.toml Files

In addition to connecting to a Teamscale server, the local project needs to be mapped to the project(s) on the Teamscale server. Since Teamscale 8.3, this is done using one or more .teamscale.toml configuration files in a simple, uniform file format (.teamscale.toml).

Configuring using Project Mappings Settings (plug-in version 8.2 and older)

In addition to enabling the Teamscale Integration, it needs to know which Teamscale project the IDE project corresponds to. This mapping is done in the Project Mappings settings page. To access the mapping settings page, you have to perform the following steps:

  1. Click File > Settings. (Alternatively, you can click Teamscale > Configure Plugin ....)

  2. Expand Tools > Teamscale > Project Mappings. This will open the following dialog:

    Creating Project Mappings

  3. In the dialog, check the option Enable Teamscale for this project.

  4. Select the appropriate Teamscale server and project values.

  5. Create prefix mappings by clicking on the Auto-create Prefix Mappings button.

  6. Click Apply and OK to save settings.

Under normal circumstances, the plugin automatically determines how to map the module files to the files in the Teamscale project. If the automatic mapping failed, a message is shown. To manually configure mappings between the local and the server's structure, you can add them in the module settings:

  1. Open the mapping settings page as mentioned above.
  2. Uncheck the option (Re)create prefix mappings.
  3. Create a mapping by clicking the + sign on the right side. Enter the mappings prefixes in the upcoming dialog. The Local Prefix is a part of your local directory structure. The Teamscale Prefix is a part of the project directory structure on the Teamscale server.

# Fetching Findings

To check if everything is configured correctly, open the Findings tool window via the menu (View > Tool Windows > Findings):

Findings Tool Window

Now you can select any resource that has findings and wait for findings to appear in the Findings tool window. The symbol on the top of the left hand side of the tool window will indicate the server's reachability state. Hover the mouse over the icon to get additional information. A click on the icon opens up the Teamscale settings.

# Refreshing Findings

In order to get an updated view of the findings of a selected folder or a file after changes in a file system, for instance by switching to a new repository or branch, click the Refresh findings button in the Findings tool window.

# Performing Pre-Commit Analysis

The IntelliJ plug-in can be used to analyze changes prior to committing them to the repository. This functionality is called pre-commit analysis. The findings of these pre-commits are shown as any other finding in the Findings tool window. The Automatic Pre-Commit Analysis option under the Teamscale tab must be enabled:

Pre-commit Analysis Option

The pre-commit analysis is started automatically when you do one of the following actions:

  • Open a file in the editor
  • Switch to an already open file in the editor
  • Save the file currently active editor
  • Save all open files

Under the hood, Teamscale treats these changes as a commit on a new, virtual branch in the repository: your pre-commit branch. If this analysis takes longer, IntelliJ will repeatedly poll the Teamscale server until analysis is done. Once analysis is finished, Teamscale will show the findings from your pre-commit branch.

Note that, by default, the Teamscale server enforces some limits on the pre-commit branch w.r.t. to the number of files that may be included in each pre-commit. These limits exist so that one overly large pre-commit upload does not disproportionately delay other analyses of other commits, whether pre-commits by other users or regular. More information is available here .

Performing On-Demand Pre-Commit Analysis (plug-in version 8.3 and older)

The IntelliJ plug-in can be used to analyze changes prior to committing them to the repository. This functionality is called pre-commit analysis. Only the files changed since the last commit that is present on the Teamscale server are uploaded and analyzed by pre-commit analysis. To compute the delta, Teamscale connects to the version control system configured for the IDE project. Currently, supported version-control systems are Git and SVN. You can trigger the pre-commit analysis by selecting Teamscale > Upload Project for Pre-Commit Analysis (as shown in the screenshot) from or via the shortcut »Alt+Shift+P«.

IntelliJ reports the findings delta after a few seconds in the Pre-Commit Results tool window as shown in this screenshot:

Pre-commit Analysis Findings Delta

The new findings are also shown in the complete findings list as shown on the left side in the screenshot, however, the Pre-Commit Results view allows you to focus on the new findings.

Under the hood, Teamscale handles the pre-commit upload as if it would be a new branch in the repository. After the upload, Teamscale shows findings from this virtual branch. To show findings from real repository branches again (e.g., after you switched to a different branch), disable the »Fetch Pre-Commit Results« toggle in the Teamscale menu.

Note that, by default, Teamscale enforces some limits to such a pre-commit upload. These limits exist so that one overly large pre-commit upload does not disproportionately delay other analyses of other commits, whether pre-commits by other users or regular. For example, pre-commit only works if your local branch is not too far ahead of what your Teamscale server has already seen and analyzed. More information is available here .

← Integrating with Visual Studio →