Skip to content
Switch branches/tags
Go to file

Octopus Project Builder

Build status

A project providing an ability to configure Octopus projects from source controlled text files (like yaml).

It is conceptually based on Jenkins Job Builder which I have found to be a great utility tool to work with Jenkins.

Using the Octopus Project Builder, together with source control system like git, gives the following benefits:

  • change history,
  • ability to use the previous version of configuration,
  • ability to create a review process before applying changes,
  • configuration editing, like extracting variables to library variable sets, or applying bulk changes to many projects.


To build project, execute a following command from Powershell: PS> .\build.ps1

Yaml configuration manual

To see the yaml configuration manual, please take a look at Configuration Manual

Supported Octopus resource configuration

Octopus resource configuration templating

OctopusProjectBuilder allows template definition for most repetative configuration sections like:

It is possible to create parameterized templates with ability to parameterize any properties of string type. It is also possible to use templates for lower configuration sections in template of higher configuration sections. For example The Project template can use Step templates that can be composed from Action templates.

For more information, please take a look at Template manual.

OctopusProjectBuilder.Console.exe usage

The OctopusProjectBuilder.Console.exe requires following paramters:

Parameter Description
a:action Action to perform: Upload, Download, CleanupConfig
d:definitions Definitions directory
k:octopusApiKey Octopus API key
u:octopusUrl Octopus Url

The download action allows to download the current Octopus configuration to the target directory, the upload action allows to apply the yaml configuration on Octopus server, while the cleanupConfig action allows to rewrite the configuration, and it is helpful to reorder nodes, reformats parameters or remove the entries with default values.


Sensitive variables

OctopusProjectBuilder.Console.exe is not able to download value of sensitive variables or parameters. The downloaded sensitive variables will have IsSensitive flag set to true, but variable will be null.

If user wants to define a sensitive variable in yaml, it is possible to specify IsSensitive:true, but the Value property will have to hold plain text value. When OctopusProjectBuilder.Console.exe uploads it, it would be kept in Octopus in encrypted format. Currently, the only possible workaround is to define a Library Variable Set with credentials in Octopus, and refer to it in the project:

- Name: My Project
  - My credentials
  # ...
  - Name: MyPassword
    Value: #{Credentials_my_password}


To see the example configuration, please browse the examples project directory.


Source control based Octopus configuration




No packages published