TeamCity On-Premises 2024.07 Help

Integrating TeamCity with Perforce

This article describes how to integrate TeamCity with Perforce Helix Core to:

  • Build sources of projects stored in a Helix Core repository.

  • Use Perforce streams as feature branches and build their sources independently of each other.

  • Pre-test and pre-build files in shelved changelists.

  • Apply automatic labels to sources.

  • Report build statuses to code reviews in Perforce Helix Swarm.


  • TeamCity supports Perforce Helix Core servers/clients starting from Helix Core 2017.1

  • A Perforce Helix Core client must be installed on the TeamCity server machine.

  • The path to the Perforce client must be added to the PATH environment variable.
    Alternatively, a full path to p4 could be set via the internal property teamcity.perforce.customP4Path. The property value must include the p4 filename.

Running Builds on Perforce Helix Core Sources

To be able to run builds on project sources stored in Perforce Helix Core and to use all the features described in this article, you need to perform two procedures:

  1. Create a dedicated project in TeamCity:

    1. Go to Administration | Projects and click Create project.
      Note that this will add the project right under the Root project. Alternatively, you can add it under any other existing project.

    2. Enter the Name and ID of the project.

    3. Click Create.

  2. Create a Perforce VCS root:

    1. In the Project Settings, go to VCS Roots.

    2. Click Create VCS root.

    3. Choose Perforce Helix Core as a VCS type.

    4. Configure the root's settings as described in this article.

After the project and Perforce root are configured, you can proceed with adding build configurations and running builds.

Running Builds on Perforce Streams

TeamCity can monitor commits in Perforce streams and work with them as with regular feature branches.

If a Perforce root is configured to use the Stream mode, you can enable the feature branches support in the root settings. After it is enabled, all streams which have the specified main stream as a parent will be included into the set of feature branches processed by TeamCity. To include only specific streams to this set, edit the branch specification to filter these streams. Each filter rule should start with a new line. The syntax is +|-:stream_name. For example, use +://stream-depot/* to monitor only streams located in the stream-depot depot, where * (for example, master) is a logical branch name. Note that streams used in the branch specification should be descendants of the main stream.

TeamCity can process task streams as well, but it only detects new task streams if there is a non-merge commit made to them.

Running Builds on Streams from IntelliJ IDE

You can launch a remote build run from IntelliJ-platform IDEs, but only if a stream has been already detected by TeamCity. The TeamCity Remote Run plugin tries to deduce the correct stream according to the depot paths of the files in the IDE's working copy.
For instance, if a file path in the working copy starts with //depot/stream1/some/path, TeamCity will try finding the //depot/stream1 stream and starting the remote run there. If you have modified a file from another stream (imported into the working copy) and want to enforce a build in a particular stream, you need to specify a configuration parameter when triggering the remote run.

Cleaning Stream Workspaces

To properly process task streams, TeamCity needs to create dedicated workspaces on the Perforce server. To save the server resources, you can clean inactive workspaces created by TeamCity directly from the TeamCity UI.

Running Personal Builds from IntelliJ IDE

If you write code in an IntelliJ-based IDE, you can pretest and prebuild local changes before committing them to a main Perforce repository: see common instructions on remote run, remote debug, and pre-test delayed commits.

The remote run/debug functionality is common for all types of VCS, but there are extra conveniences specific to Perforce:

Running Builds on Perforce Shelved Files

TeamCity allows you to run personal builds on Perforce shelved files. This way, you can try building changed source files before checking them into a common depot.

To manually run a custom build on Perforce shelved files:

  1. Open the custom run dialog by clicking the context menu next to the Run button.

  2. Enable run as a personal build option.

  3. Enter the ID of the changelist that contains the shelved files.

    Run custom build on P4 shelved files
  4. Choose the target Perforce root.

To configure automatic triggering for a Perforce shelved changelist:

  1. Go to Build Configuration Settings | Triggers.

  2. Add a new trigger of the Perforce Shelve Trigger type.

  3. Configure its settings as described in this article.

To build the target shelved changelist with TeamCity REST API, send a request to the following endpoint:

  • BUILD_TYPE_ID — the ID of your build configuration.

  • VCS_ROOT_ID — the external ID of a related VCS Root.

  • SHELVED_CHANGELIST_ID — the ID of the required changelist.

Publishing Build Statuses to Perforce Helix Swarm

If you use Perforce Helix Swarm for code review of shelved files, you can configure TeamCity to posts build statuses as comments to your reviews.

See this help article for more information: Integration with Perforce Helix Swarm.

TeamCity Workspaces in Perforce

To perform Perforce-related operations, a TeamCity server usually executes Perforce commands without the workspace context. For instance, workspaces are not required for tracking changes and for most server-side operations. However, certain cases require creating a dedicated workspace:

Learn how TeamCity creates workspaces in Perforce and works with them in this article.

Configuring Post-Commit Hooks on Perforce Server

By default, TeamCity uses a polling approach to detect changes in a VCS repository. It periodically sends requests to the Perforce server to detect new revisions. For large installations with hundreds of VCS roots, this may create a noticeable load on both Perforce server and TeamCity. To avoid background polling, you can set up a post-commit hook on your Perforce server. This hook will notify TeamCity to start checking for changes only when they are available.

TeamCity provides a dedicated hook script that should be saved on your Perforce server. You can find the detailed instruction here.

Label Perforce Sources

TeamCity can assign custom labels to Perforce project sources. The list of applied labels and their status is displayed on the Changes tab of Build Results.

To configure automatic labeling for a build configuration:

  1. Go to Build Configuration Settings | Build Features.

  2. Add a new feature of the VCS labeling type.

  3. Choose a Perforce VCS root to label.

  4. Specify the labeling pattern as described here.

View Perforce Jobs

If a build contains a changelist that is associated with one or more jobs, TeamCity will show a wrench icon wrench.png next to this change in the build results. Click or hover it to view the details of the relevant jobs.

View Perforce Logs

All operations of the Perforce plugin are logged in to the teamcity-vcs.log files with the category jetbrains.buildServer.VCS.P4 (on an agent or on a server, depending on the operation mode). The detailed logging can be enabled with TeamCity Server Logs.

Last modified: 03 June 2024