Integrating TeamCity with Perforce

Prerequisites

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

• If you plan to use the agent-side checkout mode, you need to install a Perforce Helix Core client and add it to PATH on build agent machines as well.

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 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:

• Remotely running builds on Perforce streams.

• Testing changes on shelved files without committing them to a depot.

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.

   

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 POST request with the following body to the /app/rest/buildQueue endpoint:

swarmUpdateUrl

A URL for the Perforce Helix Swarm test updates. This property is optional and used only by builds triggered by Helix Swarm.

shelvedChangelist

This property should point to a shelved changelist number and a valid VCS root external ID. The value should be in the vcsRoot.<external_id>.shelvedChangeList format.

In addition to this endpoint, you can also use a dedicated runBuildForShelve endpoint that was available prior to version 2024.12:

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.

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:

• By default, TeamCity uses agent-side checkout mode for checking out sources of a build. In this case, it creates a dedicated Perforce workspace and executes a corresponding p4 sync command to get the sources.

• Using a Perforce VCS root to store versioned project settings.

• Using Perforce streams as feature branches. In this case, TeamCity creates workspaces on the Perforce server to correctly process task streams.

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.

Perforce Service Messages

Personal builds working with Perfoce projects may fail during the final "Undo personal changes" stage. This usually occurs if the code source checkout directory becomes unavailable before this stage begins.

In such cases, you must undo personal changes earlier than TeamCity normally does — while the build steps are still running. To do so, send the following service message during the final build step: