New Release

Deploy to Amazon ECS with our guided UI step

Octopus Deploy Documentation

Configuration as Code (Early Access)

Last updated

The Early Access Preview of the config-as-code feature is available in Octopus Cloud instances, and is enabled via Configuration ➜ Features

Config as code feature toggle


Welcome to the config-as-code Early Access Preview! Support for version-controlling Octopus projects has been highly requested for a long time now, and we're excited to release the first cut. The goal of the EAP is to gather feedback, and help us evaluate which problems we have solved, and which are the most valuable to solve next.

Config-as-code is still in development. We strongly recommend not using it on critical production projects at this stage.

The config-as-code EAP adds support for configuring Octopus projects with the details of a Git repository. For the EAP, this is the deployment process which is 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.

Branch-switcher UI

Of course, there is also now a text representation of the process in the git repository, and if you prefer editing text then 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.

This 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.

What's next?

We have some strong opinions on what's next. We've always intended to version-control variables and runbooks, and we'd like to evolve the OCL schema to make it friendlier for editing by hand.

But we are very interested to hear what's important to you.

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 forms. The orange EAP chips in the product link to feedback forms 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 can be found under the Version Control navigation menu item.

Version-control configuration UI

The Git Repository field should contain the URL for the repository you wish the Octopus configuration to be persisted to. e.g.
The repository must be initialized (i.e. contain at least one branch).

The Default Branch Name is the branch on which the Octopus configuration will be written. It is the also the default branch which will be used in various situations, for example

  • When users view the project's deployment process for the first time in the Octopus UI, this is the initially selected branch
  • When creating releases, this will be the branch selected initially

For existing repositories that are initialized, the default branch must exist. If the repository is new and uninitialized, Octopus will create the default branch automatically.

The Authentication field specifies the credentials used by Octopus when authenticating with the git provider. For the Password field, we recommend using a personal access token. We also recommend that you follow the principle of least privilege when selecting scopes or permissions to grant this personal access token.

Git providers allow you to create an access token in different ways. The recommended scope for each provider is also listed in brackets.

Git File Storage Directory specifies the path within the repository where the Octopus configuration will be stored. If only a single Octopus project will be stored in the repo, we recommend putting the configuration directly under the .octopus directory. If multiple projects will be persisted to the repository, adding the project name to the path is the recommended convention, e.g. ./octopus/acme

Making changes to the deployment process

Once an Octopus project is configured to be version-controlled, any changes to the deployment process are made on a branch.

Via the Octopus UI

When editing the deployment process via the Octopus UI, the branch is selected in the branch-switcher at the top of the deployment process editor.

Branch-switcher user-interface

Via code

Changes can also be made using your favorite text-editor or IDE, and committed and pushed just as you would any other code change.

Additional options in your Build Server integration

Once an Octopus project is configured to be version-controlled, you can choose which branch to build from before creating a release in Octopus. To enable this, we have added the following two new fields to our common integrations - TeamCity, Azure DevOps, Jenkins, GitHub Actions, and Bamboo.

  • Git Reference - the user-friendly alias for a commit hash.
  • Git Commit - the commit SHA-1 hash.

When the app being built is in a different repository to the Octopus project, Octopus does not guess or auto-populate the commit or branch that you want to create the release from. Also, in the case where the app and the Octopus project are in the same repository, the head of that branch could have moved forward from what is expected. In both cases, it is highly recommended that you provide the commit and not just the branch.

Need support? We're here to help.