Octopus Deploy Documentation

Configuration as Code

Last updated


The Configuration as Code (config-as-code) feature adds support for configuring Octopus projects to store project resources in a Git repository. For now, only the deployment process and some deployment settings can be version-controlled.

It was important to us that the Octopus UI remain fully functional for version-controlled projects, and it has. You can continue to use the UI exactly as you always have, but with an additional super-power: Git branches are now exposed in the UI, allowing editing the deployment process on any branch via the UI. If you type the name of a branch that doesn't exist in your repository, you'll see an option to create that branch. This option is available when committing changes to your deployment process too.

Branch-switcher UI

Of course, there is now a text representation of the process in the git repository, and if you prefer editing text, open your favorite editor and go for it. We refer to the text format as Octopus Configuration Language (OCL), and it is very much inspired by HCL.

That means that where previously there was only a single current version of the deployment process, it is now possible to have many. When creating releases, the relevant branch can be selected. We have also added branch system variables that can be used in your custom deployment scripts.

Config-as-code only supports git repositories. Before using this feature, you should be familiar with git concepts such as distributed version control, pushing, pulling, branching, merging, and fetching.

What's next?

We have some strong opinions on what's next. The first release of config-as-code will only include the deployment process.

Our plans for future releases of config-as-code are to add support for:

  • Variables
  • Runbooks

In addition, we'd like to evolve the OCL schema to make it friendlier for editing by hand.

We want your feedback

Our major goal for the early stages of this feature is to discover the ways people want config-as-code to evolve. What scenarios would you like to see unlocked? What doesn't work the way you hoped?

You can provide feedback through whichever of the following channels you feel most comfortable with:

  • Feedback form. There is a link in a version-controlled project's Version Control Settings section that takes you to a feedback form when clicked. This is a great way to provide structured feedback.
  • Community slack. The config-as-code channel in the Octopus community slack is the best place to have a conversation with the team.
  • Support. For errors or issues, see our official support channels.

Configuring a project to be version-controlled

Version-control is configured per project and is accessed via the Settings ➜ Version Control navigation menu item.

Learn more about Configuring version control on a project.

Config-as-code reference

Several resources previously stored in SQL Server will now be stored in git once a project is version-controlled.

Learn more about Configuration as Code reference

Making changes to a version-controlled project

Any changes to the deployment process or settings are made on a branch after a project is configured to be version-controlled.

Learn more about Editing a project with version control enabled.

Creating and deploying releases

Once an Octopus project is configured to be version-controlled, you can choose which branch to build from before creating a release in Octopus.

Learn more about creating and deploying releases in a version controlled project.

Unsupported Scenarios

The Configuration as Code feature is designed to give you the benefits of source control, branching, reverting, and pull requests while being able to use your tool of choice to manage your processes (and eventually) variables. While it has many benefits, there are some unsuitable use cases and scenarios.

Learn more about unsupported config-as-code scenarios

Need support? We're here to help.