How do I use OctopusBypassDeploymentMutex properly?

Octopus version 3.3.6

We deploy to a lot of environments on the same deployment target at once (around 30). Most of the steps are quick running, but one or two could take a long time. The way the deployments currently run, it seems like it will run step one on about 5 environments (single threaded), then step 2 on those same environments (single threaded), etc, etc, etc. Once the first 5 environments are completely done, it moves on to the next 5 and follows the same process until everything is done.

The problem with this is that it potentially takes a very long time to run all of the upgrades in this fashion. We were toying with the idea of using the OctopusBypassDeploymentMutex flag, but we do have some steps that we would not want to run at the exact same time on the same machine. I tried setting Octopus.Acquire.MaxParallelism in my variables to reduce the amount of packages it downloads simultaneously, and I tried setting Octopus.Action[Action Name].MaxParallelism to reduce the amount of processes that can simultaneously run a particular step. Neither of these flags seemed to work the way I had expected.

I would really just like some further guidance on how to best utilize these settings to deploy to our environments on a shared deployment target in a more timely fashion.

Ideally, I would like to run all deployment steps on as many deployment targets as possible at the same time (multi-threaded), and just have a few steps that cannot be run in parallel. This would drastically speed up our deployments. Is there any way to accomplish something like this?


Hi Eben,

Thanks for getting in touch! It looks like you are running into the same problem as your colleague in this question, can you take a look at the Task Cap setting mentioned in that response and see if that helps you. If not let me know and we can look at what other options are available.

Hope that helps!


Thanks Mark!

I was not aware of this setting on the server, and that will help a lot. I also did not realize how similar Girvan’s question was to mine :slight_smile:

I am still interested, though, in a little more guidance on how OctopusBypassDeploymentMutex works along with Octopus.Acquire.MaxParallelism and Octopus.Action[Action Name].MaxParallelism. I was attempting to utilize them, and I was either misunderstanding how they work, or I was not using them correctly. Octopus.Acquire.MaxParallelism did not appear to limit the number of packages that were downloaded on the tentacle at once, and I was having a hard time verifying if Octopus.Action[Action Name].MaxParallelism was doing what I wanted (essentially, I was trying to make certain steps not run in parallel).


By default individual Actions in a Project run sequentially, but are run on all machines targeted by that action in parallel. To limit the number of machines the action is run on at a time you can set Octopus.Action.MaxParallelism.

To get certain Steps to run in parallel you need to explicitly opt in by following the instructions here

When doing package acquisition, all packages are downloaded in parallel, but, again as you note, you can limit that with Octopus.Acquire.MaxParallelism. These settings were originally designed around reducing the load on the Octopus server, so if you are downloading a package from an external package feed directly to the Tentacle we currently ignore this setting, since it doesn’t touch the server.

Note that neither Octopus.Action.MaxParallelism nor Octopus.Acquire.MaxParallelism can be scoped to a single Action with the [Action Name] syntax.

By default, even if you have configured two steps to run in parallel, if they run on the same machine the deployment mutex will prevent them from running on the same machine at the same time. This also prevents steps in different projects from running on the same machine at the same time. If you want to override this you can use OctopusBypassDeploymentMutex. Generally it is safer to not use this unless you are really sure you need it.

I hope that clears some things up. Please let me know if you need any more information.