Perforce

TeamCity can integrate with Perforce to build source projects stored in Perforce Helix Core and ensure their continuous integration and delivery. Learn more about this integration here.

This article describes the settings specific to a Perforce Helix Core VCS root. Common VCS root settings are described here.

P4 Connection Settings

Setting	Description
Port	Define the Perforce server address as `host:port`. For specific environments, the `P4Host` environment variable can be set in the Workspace options below, for any type of checkout.
Stream / Client / Client mapping	Choose the connection mode. See the details below.
Username	Specify the user login name.
Password or Ticket	Optionally, specify the password or ticket. If you enter a value, TeamCity will: Set it as the `P4PASSWD` environment variable for executing Perforce commands, or Use it as the ticket in the `p4 login` command, if password-based authentication is disabled on the Perforce server. If you leave the field empty, TeamCity will rely on an existing P4 ticket of the current user (p4ticket.txt). If the ticket is not present in this file but required for authentication with Perforce, the failure will occur. The ticket file should be present on the TeamCity server machine and on all build agents where TeamCity runs Perforce builds for this VCS root.
Ticket-based authentication	Check this option to enable ticket-based authentication. This option is enabled by default and not displayed.

Use Perforce Streams

Choose the Stream option to use an existing Perforce stream. TeamCity will use this stream to prepare the stream-based workspace and adjust the client mapping to it.

Notes on using this mode:

The Stream field format:
- Supports a deep structure specification, that is paths like //DEPOTNAME/1/2/n.
- Supports build parameters.
To use the StreamAtChange option, you need to define Label/changelist to sync.
When streams are used with the agent-side checkout mode, simple checkout rules like . => sub/directory are supported. Exclude checkout rules, multiple include rules, or rules like aaa=>bbb are supported only when the "Create non-stream workspace" option is enabled (see below).
When task streams are used for feature branches, TeamCity may miss some changes in task streams until a modifying commit is made, which means that merge commits from the parent stream are not detected until a real commit to the task stream is made (see ticket TW-44765).
Note that Perforce support in TeamCity treats checkout rules as case-sensitive. Case-insensitivity for Perforce-based build configurations can be enabled on the Version Control Settings page by adding the following comment in the Edit Checkout Rules form: ##teamcity ignore-case.

The "Enable feature branches support" option allows you to specify branch streams to be monitored for changes, in addition to the default one. Read more about this functionality.

Use Perforce Client

The Client option allows specifying the client workspace name directly. The workspace must be already created by a Perforce client application (like P4V or P4Win). Only mapping rules from the configured client workspace are used. The client name is ignored.

Notes on using this mode:

When this option is used with the server-side checkout, the internal TeamCity source caching on the server side is disabled. This may worsen the performance of clean checkouts.
If a build configuration has a configuration parameter teamcity.perforce.agent.reuse.client=true and uses default checkout rules, TeamCity won't create another Perforce workspace on agent and will try to reuse the existing Perforce client, with the name specified in the Perforce VCS root.

Map Perforce Depot to Client

The Client mapping option allows specifying the mapping of the depot to the client machine.

Notes on using this mode:

The Client mapping field format:
- TeamCity will handle file separators according to the OS/platform of the build agent where a build is run. To be able to use a specific line separator for all build agents, choose the Client or Stream option instead (with LineEnd specified in Perforce). Alternatively, you can add an agent requirement to run builds only on a specific platform.
- Use team-city-agent instead of the client name in the mapping.
  Example:
  //depot/MPS/... //team-city-agent/... //depot/MPS/lib/tools/... //team-city-agent/tools/...
If the direct client mapping is changed, a clean checkout will be forced.
Changing client mapping will not force clean checkout for the agent-side checkout when:
- A Perforce client name is used: changing the Perforce client mapping for the client will not result in a clean checkout.
- A Perforce stream is used: changing the stream name while keeping the same stream root will not result in a clean checkout.

Using ChangeView

To focus on specific revisions, use the ChangeView specification:

//depot/... //team-city-agent/... ChangeView: //depot/dir1/…@90 //depot/dir2/…@automaticLabelWithRevision

where 90 is the number of the exact revision of dir1 and automaticLabelWithRevision is the labeled revision of dir2. All the other revisions of these directories will not be monitored by this VCS root.

Agent Checkout Settings

When the agent-side checkout is used, TeamCity creates a Perforce workspace for each checkout directory/VCS root. These workspaces are automatically created when necessary and are automatically deleted after a timeout. See more details on Perforce workspace handling.

Setting	Description
Workspace options	Optionally, set the following options for the `p4 client` command: `Options`, `SubmitOptions`, and `LineEnd`. For specific environments, define `P4Host` (supported for any type of checkout). See the details on workspace parameters below.
Create non-stream workspace	Available only for Streams Enable to be able to check out sources using a non-stream workspace based on the stream specification. This allows using checkout rules but makes it impossible to commit to the stream within the build.
Run 'p4 clean' for clean-up	Enable this option to clean up your workspace from extra files before a build. If enabled, the `p4 clean` command will be run before `p4 sync`, unless `p4 sync -f` or `p4 sync -p` is used. See the command reference.
Skip the have list update	Enable this option to not track files on the Perforce server on synchronization (always transfer all files to the agent, `p4 sync -p`). If disabled, TeamCity will use `p4 have` to keep the list up to date.
Extra sync options	Specify additional `p4 sync` options. If you need to specify the list of options that should be declared after the `sync` command, omit the name of this command. For example: Enter `--parallel=threads=5` to run the `p4 sync --parallel=threads=5` command. To specify options that should be declared both before and after the `sync` command, include the command name in this list of extra options. For example: Enter `-r3 sync` to run the `p4 -r3 sync` command. Enter `-r4 sync --parallel=threads=5` to run the `p4 -r4 sync --parallel=threads=5` command. See the `command reference` for more information.

Perforce Workspace Parameters

TeamCity stores connection variables of each Perforce VCS root in the following parameters:

%vcsRoot.extId.port%
%vcsRoot.extId.user%
%vcsRoot.extId.p4client%

where extId is the VCS root's external ID, specified in its settings.

This way, you can access them from a script separately for each root.

With checkout on an agent, TeamCity provides environment variables describing the Perforce workspace created during the checkout process.
If several Perforce VCS roots are used for the checkout, the variables are created for the first VCS root. The variables are:

P4USER — same as the vcsroot.<VCS_root_ID>.user build parameter.
P4PORT — same as vcsroot.<VCS_root_ID>.port.
P4CLIENT — same as vcsroot.<VCS root ID>.p4client, the name of the generated P4 workspace on the build agent.

These variables can be used to perform custom p4 commands after the checkout.

See more details

Perforce Proxy Settings

To allow using Perforce proxy with the agent-side checkout, specify the env.TEAMCITY_P4PORT environment variable on the build agent, and the agent will take this value as the P4PORT value.

Other Settings

Setting	Description
P4 path on the build agent	Specify the path to the Perforce command-line client (`p4.exe`). This works only for the agent-side checkout. On the agent side, the value of this parameter could be overridden via the `TEAMCITY_P4_PATH` environment variable, if such a variable is set in `buildAgent.properties` or comes from build parameters.
Label/changelist to sync	Specify the label if you want to check out sources not with the latest revision, but with a specific Perforce label (with selective changes). For instance, this can be useful to produce a milestone / release build. If this field is empty, the latest changelist will be used for synchronization. If you use symbolic labels, consider using the agent-side checkout. With the server-side checkout on label, TeamCity will perform full checkout.
Charset	Select the character set used on the client machine.
Support UTF-16 encoding	Enable this option if you have UTF-16 files stored as the `utf16` Perforce file type in your project. You may want to enable this option if you use server-side checkout and have files of the `utf16` Perforce file type in your depot. Enable it to keep the `UTF-16` encoding in the checked out files. Otherwise, such files may be converted to `UTF-8` upon checkout. If you store `UTF-16` files as the `binary` Perforce file type, they will always be checked out "as is", no conversion will be performed.
P4 trust	If a VCS root of your project connects to Perforce via SSL, TeamCity will automatically establish a trusted connection to it. The `p4 trust` command is sent every time you test a Perforce connection, or a build agent checks out sources from Perforce. If the SSL certificate on the Perforce server is renewed, the agents need to be configured to trust this new certificate with the help of a special parameter. For security reasons, this parameter needs to be removed after all agents have checked out the sources. Set the `teamcity.internal.perforce.forceTrust=true` configuration parameter to the related project or build configuration.

Last modified: 07 September 2023