This documentation is for Octopus Deploy Version 2018.12. View other versions

Substitute Variables in Files

Last updated

The Substitute Variables in Files feature is one of the configuration features you can enable as you define the steps in your deployment process. This feature is available in package steps, and it allows you to inject Octopus Variables into any file.

Octopus will parse the files you select for variable binding expressions, replacing each expression with its result.

You can perform very complex transformations in any kind of file using this feature. We also have features tailored to XML configuration files and JSON configuration files.

How to Substitute Variables in a File

The following example shows you how to use the Substitute Variables in Files feature to provide a different login form to the different environments you're deploying to, in this example we're deploying to a Test and Production environment.

  1. Create the login variable in Octopus. From the: project overview page, click Variables.
  • Enter a the name for the variable, for instance, LoginURL.
  • Enter the value for the variable, for instance,
  • Scope the variable to the environment, for instance, Test.
  • Repeat the process for the production environment, to give you a different value for the loginURL variable for each environment and click SAVE. In this example, you would have variables similar to the following:
Variable Name Value Scope
LoginURL Test
LoginURL Production
  1. Include the loginURL variable in the app you're deploying. For instance:
    <authentication mode="Forms">
      <forms loginUrl="#{LoginURL}" timeout="2880" />
  1. Define the deployment process, by clicking Process from the project overview page, then selecting, ADD STEP.
  2. Select the Deploy a Package step.
  3. From the Step Template page, click the Configure Features link.
  4. Check the Substitute Variables in Files checkbox and click Ok.

Substitute Variables in Files feature

When you return to your deployment process, you will see the Substitute Variables in Files option has been added to the Features section of the deployment process.

  1. Add the step details:
  • Enter a name for the step.
  • Select the targets where the step should run.
  • Select the package feed where the package will be available.
  • Enter the package ID for the package to be deployed.
  1. In the Target Files text area, enter the files, as a newline separated list, that you want to perform the variable substitution on. In our example, that includes any file that references the LoginURL variable.

Each file needs to be defined on a new line in the text area. You need to state the full path of the file, relative to the installation directory. So, if you need to replace variables on a file called app.config that is inside of a config folder on the root of your package, you need to put config\app.config in the Target files field.

You can also use Octopus embedded template syntax to conditionally list files that only need replacement on specific environments.

  1. If you want to specify the encoding for the transformed file, enter the encoding in the Output file encoding field.

The default option for Output file encoding (Detect from template) will use the Byte Order Mark (BOM) of the file to determine the encoding.

  1. Add any conditions you need to specify for the step, and then click SAVE.

Now, when the application is deployed to your test and production environments, will include the login URL you defined for the specific environment.

From here you can use the project overview menu to continue defining your process, or click CREATE RELEASE to create a release and deploy your application.

If you include a configuration file that you are also doing a transformation and variable swap on, the variable change will run under the 'substitute variables in files' before the transformation as defined in the package deployment feature ordering process.

By default warnings will be treated as errors when replacing variables in files using this feature. To override this behavior, set the variable Octopus.Action.Package.IgnoreVariableReplacementErrors to True in your project. By doing this, warnings will be treated as such and the deployment wont be marked as failed.


Swapping Design Elements

If you want to include a header that has a different image or text in a shared layout file depending on environment that it is deployed to. You can define the file and put a variable in place where you want the change to be. In this example, we've used the SiteReference variable:

          <div class="navbar-header">
            <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
              <span class="sr-only">Toggle navigation</span>
              <span class="icon-bar"></span>
              <span class="icon-bar"></span>
              <span class="icon-bar"></span>
            <a class="navbar-brand" href="#">OctoFX #{SiteReference}</a>

Spring Boot Application Properties

Another common scenario is updating a Spring Boot file to set the web server port. In this example, we’ve used the WebServerPort variable:


The Spring expression language also uses the #{} syntax so you need to double encode any non-Octopus variables. i.e. ##{MyVariable}.