TeamCity On-Premises 2024.12 Help

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 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 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 file or comes from build parameters.

For the server, the p4 binary should be present in the PATH environment variable of the TeamCity server machine, or can be specified via the teamcity.perforce.customP4Path internal property.

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. When TeamCity syncs sources using labels, it writes the revision number to the vcsRoot.{externalId}.changelist parameter.

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: 06 November 2024
MercurialStarTeam