Using Perforce with Bamboo - limitations and workarounds

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

There are some limitations to using Bamboo with Perforce. Please read the following information carefully before setting up a build plan to use Perforce.

On this page:

1. Running builds on multiple remote agents or machines


You will not be able to run builds on multiple remote agents and/or multiple remote machines using a Perforce repository, without using one of the workarounds described below. If you try to do so, you will run into problems with change detection that could cause your agents to build incorrect code. This problem does not affect the running of builds on multiple local agents.


Perforce is a client/server SCM (software configuration management) system that manages your changes/files by storing the change information on its server. However, storing change information on the Perforce server can cause problems when you have clients on multiple agents/machines. If you have downloaded a particular change with a Perforce client, the change will be marked as downloaded by the Perforce server. If you use the same Perforce client on another machine, the Perforce server will incorrectly assume that you have already downloaded that particular change and will not download it. Hence, your agents may not pick up changes correctly and could build incorrect code.


There a few workarounds available for this issue, if you are using Perforce with Bamboo:

  • Restrict your plan to use a single machine — you can use one or more remote agents to build a plan, if they are running on the same machine and you set the client root yourself (i.e. do not let Bamboo manage your workspace) so that your agents will build to the same directory.
  • Make Bamboo force a clean build every time it builds — this will ensure that your agents are always building the correct code. However, it can be an inefficient setup for big projects.
  • Use alternate roots for different machines — specifying alternate roots for different machines will allow you to work around the change detection issue, as long as the roots on each machine are unique. Please note however, you will be restricted to three machines (with three different roots) due to Perforce limitations.

Please see the following Jira issues for further information, BAM-2843 and BAM-2774.

2. Using Perforce Overlay and Exclusionary Mappings in Bamboo


You will not be able to control how Bamboo detects changes using exclusionary mappings or overlay mappings.

(info) Please note, this issue does not affect you if you only trigger your builds on a schedule or manually, as Bamboo agents still build the correct code when triggered.

(info) You may want to try the Use client mapping for change detection option available in the Bamboo Perforce repository type.


Bamboo currently uses the depot view, not the client view, when detecting changes. Hence, any exclusionary and overlay mappings will not be available during change detection.

For example, if a p4 client uses an overlay mapping like this one:

//depot/Prj/... //clientName/depot/Prj/...
+//depot/Dep/... //clientName/depot/Prj/Dep/...

and the Depot specified in a plan's repository configuration is:


then Bamboo will lookup the corresponding depot view and detect changes by running the following command:

p4 changes //depot/Prj/...

Consequently, no changes to files in //clientName/depot/Prj/Dep/... will be picked up by change detection, despite the overlay mapping.

Hence, if you set up your build to trigger when code is updated it will not trigger correctly.


A partial workaround is available in Bamboo, if you wish to use exclusionary mappings for your client workspace. Specify your build plan to exclude files that match a specified pattern by selecting Exclude all changes that match the following pattern from the Include / Exclude files dropdown (under the Common repository configuration section). See Perforce configuration for further details. Please note, this will only exclude one pattern whereas multiple exclusions can be specified in an exclusionary mapping.

Unfortunately, there is no workaround for overlay mappings in Bamboo.

Please note, we are aware of these problems and are working to address them — see the following Jira issue for further information, BAM-3323.

Last modified on May 25, 2021

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.