Perforce Workspace Handling in TeamCity
To perform Perforce-related operations, TeamCity usually operates in a "no-workspace" mode, that is it executes Perforce commands without the workspace context. For instance, workspaces are not required for tracking changes or for most server-side operations.
The cases when a workspace is created are:
If agent-side checkout is enabled (it is the default checkout mode). In this case, TeamCity creates a Perforce workspace to check out the build sources.
Using versioned project settings with Perforce Helix Core.
Using Perforce streams as feature branches. In this case, TeamCity creates workspaces on the Perforce server to correctly process task streams.
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
If your build configurations use the agent-side checkout, you can modify a workspace name as follows:
Add a workspace name prefix via the
Set a custom workspace name in case your workflow requires a specific workspace name pattern. To do this, set the
vcsroot.<VCSRootExternalID>.p4clientparameter. 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
P4PORT— same as
P4CLIENT— same as
vcsroot.<VCS_root_ID>.p4clientparameter, 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.
Deleting Workspace on Build Agent
TeamCity deletes the Perforce workspaces in the following scenarios:
Immediately after a versioned settings commit (a workspace is created for each commit).
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.expireHourssystem 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=falsesetting, either in the
buildAgent.propertiesfile or globally at the server level as a Root project configuration parameter.
When deleting a Perforce workspace which contains pending changes or opened files, TeamCity tries to revert the changes and remove pending changelists, and after that repeats the operation. If the second attempt fails as well, TeamCity tries to run the
p4 client -d -foperation (forced). All those actions are logged to
TeamCity does not force workspace deletion when a Perforce edge/replica server is used.
Cleaning Workspaces on Perforce Server
If you enable the feature branches support in a Perforce VCS root, TeamCity will start processing your Perforce task streams. To do this correctly, it needs to create dedicated workspaces on the Perforce server. Over time, these workspaces might consume a significant amount of resources on this server's machine. You can clean no longer necessary workspaces directly from the TeamCity UI.
To establish direct access to your Perforce server, go to Project Settings | Connections in TeamCity and add a Perforce Administrator Access connection. In its settings, enter the host and user credentials for accessing the Perforce server (the user must have the
admin permission), and TeamCity will connect to it.
During every clean-up, TeamCity will detect and delete workspaces that have been inactive for more than 7 days. You can also delete them anytime by clicking Delete workspaces right in the connection settings. Note that workspaces are deleted only on the server — not on build agents — and only if they were created by TeamCity.
It is also possible to delete only workspaces associated with a specific stream. To do this, go to Build Configuration Home, open the Actions menu, and click Delete Perforce stream workspaces. By default, this action is available to all users with the Project Developer role.
In the opened dialog, specify a path to a stream, and TeamCity will delete the related workspaces on the Perforce server. To connect to the server, TeamCity will use the settings from the project's Perforce Administrator Access connection. If it is not available, it will use the Perforce VCS root settings instead.
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.
Errors During Checkout
When an error occurs during a checkout, or a build is interrupted/stopped during the checkout, or a timeout occurs, no clean checkout will occur for the subsequent builds on the same build agent. Instead, TeamCity will rely on the Perforce ability to recover from the state.
VCS Root Client Mapping Modification
Usually, when a project administrator modifies a VCS root client mapping specified in the VCS root, this is considered a change in the VCS root settings and results in a clean checkout. This clean checkout behaviour can be disabled using the
teamcity.perforce.enable-no-clean-checkout=true internal property.
teamcity.perforce.enable-no-clean-checkoutinternal property results in one-time clean checkout for all affected build configurations.
When a VCS root is configured to use Client Name, or Stream, no clean checkout will occur when the client mapping of the corresponding client/stream is edited in Perforce.
Forced Protection Against Clean Checkout
To protect a build configuration from the TeamCity-initiated clean checkout, you can set the
teamcity.agent.failBuildOnCleanCheckout configuration parameter to
true. In this case, TeamCity will fail a build instead of running a clean checkout. It will never clean the workspace, unless it is explicitly requested via the Enforce clean checkout action or if the "Clean all files in the checkout directory before the build" option is enabled in the checkout options of the version control settings for a build configuration.
When using a custom checkout path, TeamCity will not clean the checkout directory when VCS settings are changed — it will fail a build instead. To ignore clean checkout and proceed with incremental checkout, use the
teamcity.agent.failBuildOnCleanCheckout=ignoreAndContinue parameter for a project or build configuration. Do this only if you are absolutely sure that the sources in the checkout directory are in the correct state.
The same applies to the broken personal builds. When the sources are corrupted and this option is set, TeamCity will fail the build instead of running a clean checkout. You can clean the working copy via
p4 clean and try to continue with the
ignoreAndContinue value after this (to run a custom build with the specified configuration parameter).
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:
teamcity.agent.failBuildOnCleanCheckout=ignoreAndContinueparameter to your build configuration to explicitly disable clean checkouts.
To make adjustments to a workspace before the checkout starts, enable Bootstrap steps.
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;
p4 -c <p4_workspace_name> flush <changelist_revision>command to tell the Perforce server a workspace already has all required sources;
- 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.