Runbook variables

Getting Started - Variables

Octopus supports variables so that your deployment processes and runbooks can be parameterized. This allows your processes to work across your infrastructure without having to hard-code or manually update configuration settings that differ across environments, deployment targets, channels, or tenants.

For instance, when you deploy software into your test environment, you may need to provide the connection string for the test database, and when you promote the release to production, you need to provide the connection string for the production database. By assigning the connections strings as variable values and scoping those values to the test and production environments, the same deployment process works for both environments. When the software is deployed to test, the test database is used, and when the software is deployed to production, the production database is used:


You can manage the variables for your projects, by navigating to your project in the Project tab of the Octopus Web Portal and selecting Variables:

Project variables

Variables in runbooks

A project’s variables are available to both the runbooks and the deployment process, and the process for consuming variables is the same (see an example).

Variables specific to a runbook

There are scenarios where a variable may be specific to a runbook, and you don’t want it to be available to other runbooks or the project’s deployment process (this situation is common for prompted variables).

Scoping a variable to a process

Variables can be scoped to specific runbooks, or to the deployment process, by navigating to Project ➜ Variables, adding a new variable, and defining the scope. On the scope dialog, there is a Processes field, which when populated restricts the variable availability to only the selected runbooks or deployment process.

Prompted variables in runbooks

Prompted variables can be defined for runbooks. By default, prompted variables will prompt for the value when deploying or when running a runbook. By scoping prompted variables to one or more processes, they can be restricted to only prompt when deploying or for specific runbooks.

Runbooks variables in Git projects

When snapshotting a Runbook in a Git project, the variables will always be taken from the default branch. The Git reference and commit that was used to create the snapshot is shown on the Runbook snapshot page.

Screenshot of Octopus Runbook snapshot page showing variable snapshot with reference main and commit d6cff1a

To use a different branch to snapshot variables, you will need to change the default branch for the project.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023