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 For specific environments, the |
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:
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. |
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 likeaaa=>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 between two builds, a clean checkout for the second build will be forced, unless the
teamcity.perforce.enable-no-clean-checkout
internal property is set on the server.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 For specific environments, define |
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 |
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, |
Extra sync options | Specify additional |
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 ( This works only for the agent-side checkout. On the agent side, the value of this parameter could be overridden via the For the server, the p4 binary should be present in the |
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. |
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 You may want to enable this option if you use server-side checkout and have files of the If you store |
P4 trust | If a VCS root of your project connects to Perforce via SSL, TeamCity will automatically establish a trusted connection to it. The 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 |