The Power of Configuration Transformations

Published on: 15 Oct 2015 by: Shane

It is a common scenario to perform different configuration transforms depending on the Environment that is being deploying to. For example: Web.config may require different values for Development, Testing and Production. The Octopus configuration transforms feature supports common scenarios automatically by looking for Web.Development.config when deploying to Development and applying the appropriate configuration transformations to Web.config. While this is great for most people, there is sometimes a need to specify custom rules and do conditional transformations.

Custom Configuration Transformations

When editing a "Deploy Nuget Package" step in a deployment process it is possible to specify additional configuration transformations that will be performed during the deployment.

You may want to apply transformations that Octopus does not automatically recognise:

MyCustomTransform.config => Web.config

This rule will transform Web.config with MyCustomTransform.config.

The configuration transformation specification supports Octopus variables. This allows custom transformations to be applied when a file name matches a rule specification. For example, you may want to apply a non-standard configuration transform in each environment:

MyCustomTransform.#{Octopus.Environment.Name}.config => Web.config

This rule will look for a file matching the current Environment being deployed to and apply that configuration. When deploying to Production, MyCustomTransform.Production.config will be applied to Web.config.

Conditional Transformations

A powerful feature of the variable substitution syntax is the support for conditionals. When combined with Project variables, specifying custom configuration transformations can become quite sophisticated. Consider the blue-green deployment scenario. There are two Environments: "Production - Blue" and "Production - Green". It would be undesirable to maintain two separate configuration files, Web.Production - Blue.config and Web.Production - Green.config, when they are essentially the same.

A solution would be to use a condition to specify the Production transformation:

#{if IsProductionEnvironment}
    Web.Production.Config => Web.config

Then, use a variable to specify which Environments are Production:

The variable IsProductionEnvironment is set the false by default and scoped to true for the Environments "Production - Blue" and "Production - Green". When the package is deployed to either of the production Environments the Web.Production.Config transform will be applied.


Performing configuration transformations with Octopus will happen automatically in most situations but the ability to specify additional transformations makes the feature powerful. When combined with Octopus variables, configuration transformations provide a flexible way to manage settings in each of your Environments.

Octopus Deploy is used by thousands of developers across the globe, from small companies to large enterprises. Find out if it meets your deployment automation needs by taking advantage of our free 30-day trial. You can spin up an instance with just a few clicks!