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

JSON Configuration Variables Feature

Last updated

The JSON Configuration Variables feature is one of the configuration features you can enable as you define the steps in your deployment process.

The JSON Configuration Variables feature updates your JSON configuration files with the values from matching Octopus variables. In many ways this feature works similarly to the Substitute Variables in Files feature, but uses a special matching syntax so you can update configuration nested in JSON object and array literals.

This feature is designed to work natively with .NET Core JSON configuration files but works equally as well with any JSON files.

Our ASP.NET Core web application deployment guide provides further information on how this feature fits into an Octopus project's deployment process.

Configuring the JSON Configuration Variables Feature

Step 1: Enable the Feature

To configure a package step to replace matching app settings in your JSON configuration files ensure the JSON configuration variables feature is enabled.

Feature Configuration

Step 2: Configure Which Files to Update

Next, specify the relative paths within the package to your JSON configuration files.

Relative path example
Your relative path may look something like:


Note that you can even use the Variable Substitution Syntax patterns in this file selection input box itself to do things like reference environment specific files, or conditionally include them based on scoped variables.

JSON variable substitute

Any matching variables in the JSON file will have their values replaced with the variables you have configured in Octopus.

How Your JSON Configuration Settings Are Updated by Octopus

When this feature is enabled, Octopus will find the target files and replace any matching configuration settings with the value of matching Octopus variables.

Simple Variables

Given this example of a target config file:

Simple target file

   "weatherApiUrl": "",
   "weatherApiKey": "DEV1234567",
   "tempImageFolder": "C:\temp\img"

If you have the Octopus Variables weatherApiUrl and weatherApiKey set to the values and TEST7654321 the target config file is updated to become, noticing the tempImageFolder setting remains untouched:

Simple JSON

   "weatherApiUrl": "",
   "weatherApiKey": "TEST7654321",
   "tempImageFolder": "C:\temp\img"

Hierarchical Variables

It is common (and encouraged) to use hierarchical variables in JSON configuration files.  This is supported in Octopus Deploy variables by using a nested path syntax delimited by colon characters.

For example, to update the value of weatherApi.url and weatherApi.key in the target config file you would configure the Octopus Variables weatherApi:url and weatherApi:key.

Hierarchical JSON

   "weatherApi": {
      "url": "",
      "key": "DEV1234567"

You can also replace an entire object. For the example above you could set Octopus Variable weatherApi to a value of {"weatherApi":{"url":"","key":"TEST7654321"}}

Array Variables

Octopus Deploy can also replace a value in a JSON array by using the zero-based index of the array in the variable name.

For example, the variable foo:bar:1 with a value qux will update the value of the second element in the array to be qux:

Hierarchical JSON

   "foo": {
      "bar": [

You can also replace an entire array. For the example above you could set Octopus Variable foo:bar to a value of ["baz","qux"].