Perforce Workspace Handling in TeamCity

Perforce Workspace Name

The names of the created workspaces start with the TC_p4_ prefix. To support feature branches, workspaces created on the Perforce server side have the TC_p4_server_ prefix.

If your build configurations use the agent-side checkout, you can modify a workspace name as follows:

• Add a workspace name prefix via the teamcity.perforce.workspace.prefix configuration parameter.

• Set a custom workspace name in case your workflow requires a specific workspace name pattern. To do this, set the vcsroot.<VCSRootExternalID>.p4client parameter. If a custom workspace name is specified, TeamCity updates the workspace according to corresponding VCS root settings (for example, applies related stream parameters if the VCS root has the stream support enabled) before the checkout. See also: Reuse Checked Out Sources on Cloud Agents.

The workspace name also includes the build agent name and a hash value built from the checkout directory and (optionally) checkout rules.

Perforce Workspace Parameters

With agent-side checkout, TeamCity provides environment variables describing the Perforce workspace created during the checkout process.

If multiple Perforce VCS roots are used for the checkout, the variables are created for the first VCS root in the list of the build's VCS roots:

• P4USER — same as vcsroot.<VCS_root_ID>.user parameter.

• P4PORT — same as vcsroot.<VCS_root_ID>.port parameter.

• P4CLIENT — same as vcsroot.<VCS_root_ID>.p4client parameter, the name of the generated P4 workspace on the agent.

These variables can be used to perform custom Perforce commands after the checkout. For example, to be able to access the port of the PerforceTest VCS root, define the env.P4PORT=%vcsRoot.PerforceTest.port% environment variable in the project or build configuration settings.

Workspace Deletion

Perforce workspaces is a set of files on a user’s machine that mirrors a subset of the files in the depot. TeamCity automatically creates workspaces on agent machines and Perforce server. Over time, these workspaces might consume a considerable amount of resources on a server/agent machine, so you might want to periodically clear them.

Default deletion mechanism

By default, TeamCity deletes agent Perforce workspaces in the following cases:

• Immediately after a versioned settings commit (a workspace is created for each commit).

• For the agent-side checkout — when a clean checkout is performed (TeamCity will also run p4 sync -f in this case, see details below).

• In the background of the agent process (between builds), when it detects a non-existing workspace directory for a workspace associated with the current agent. A TeamCity agent performs a clean-up of unused checkout directories (the default timeout is 8 days, can be changed with the system.teamcity.build.checkoutDir.expireHours system property). When a checkout directory is deleted, and this directory is associated with a Perforce workspace, this workspace is deleted as well. Cleaning Perforce workspaces can be disabled via the teamcity.perforce.workspace.cleanup=false setting, either in the buildAgent.properties file or globally at the server level as a Root project configuration parameter.

Perforce connection settings

Enable the Automatically remove Perforce workspaces option in the Perforce Administrator Access connection settings to automatically clean TeamCity-generated workspaces that remain inactive for 7 days or more. Workspaces are removed on periodic data clean-ups.

• Affects all build configurations inside the project that owns this connection, as well as its subprojects.

• Server workspaces are automatically removed regardless of the Automatically remove Perforce workspaces option state.

• Agent workspaces created by TeamCity cloud agents (start with the TC_p4 name prefix) are removed if the corresponding setting is enabled. Workspaces created by bare-metal agents are not affected.

• The user whose credentials are entered in connection settings must have the "admin" permission.

• You can add the teamcity.perforce.keepWorkspaces=true property to cloud agent properties to keep automatic workspaces for this agent and exclude it from periodic clean-ups.

VCS root settings

Enable the Automatically remove Perforce workspaces option in Perforce VCS root settings to automatically clean TeamCity-generated workspaces after a build finishes.

• Affects only those build configurations to which this VCS root is attached.

• Removes agent workspaces on both bare-metal and cloud TeamCity agents.

• Workspaces are removed after a build finishes, which forces a clean checkout for every new build.

• The teamcity.perforce.keepWorkspaces=true property does not prevent agent workspaces from being removed if this VCS root option is enabled.

Remove workspaces manually

Click Delete Perforce workspaces... item in the configuration Actions menu to perform a one-time clean-up.

• This action allows you to clear both agent and server workspaces.

• To clear server workspaces, you need to enter a path to a Perforce stream.

• Clearing agent workspaces allows you to set the inactivity threshold (in days). Workspaces older than this limit will be removed.

Perforce Sync -f and Workspace Reuse

When the agent-side checkout is used, TeamCity creates a workspace which is bound to the checkout directory on an agent. The checkout is performed with an incremental p4 sync command (both for personal and non-personal builds).

When a VCS root is configured to use p4 sync -p, TeamCity always runs this command to check out the sources.

Usually, each clean checkout build results in p4 sync -f command with cleaning the sources. For the Perforce agent checkout, there are exceptions described below.

Reuse Checked Out Sources on Cloud Agents

To avoid clean checkouts on each new TeamCity cloud agent, you can copy or mount a persistent storage with code sources to the agent checkout directory. However, since Perforce keeps track of workspaces, agent IP addresses and names, revisions stored on agents, and other data, running a build on a new cloud agent causes the p4 sync operation to ignore existing source files and result in a clean checkout.

To prevent this from happening and reuse sources from a persistent storage, do the following:

1. Add the teamcity.agent.failBuildOnCleanCheckout=ignoreAndContinue parameter to your build configuration to explicitly disable clean checkouts.

2. To make adjustments to a workspace before the checkout starts, enable Bootstrap steps.

3. Add one or multiple command-line or script steps to your configuration and check their Run during bootstrap option. These bootstap steps should do the following:

   • ensure that the build checkout directory points to your persistent storage and this storage has all required sources checked out at the correct revision;

   • run the p4 -c <p4_workspace_name> flush <changelist_revision> command to tell the Perforce server a workspace already has all required sources;

   • set the custom workspace name to the required value. To do that, send the setParameter Service Message that assigns a new value to the vcsroot.<VCSRootExternalID>.p4client property.

     echo "##teamcity[setParameter name='vcsroot.P4_ExternalVCSRootID.p4client' value='customP4ClientName']"

With these bootstrap steps in place, TeamCity updates your P4 client specification, runs the p4 sync command and performs a checkout that should fetch only changes between the flushed <changelist_revision> and the revision associated with the current build.