Environment state lets a deployment or runbook run store important values generated during the process for later use. Future deployments and runbook runs for the same project, environment, and tenant get access to these state values as variables.
A primary use case for environment state is provisioning and deprovisioning ephemeral environments. For example, a provisioning runbook creates a Kubernetes namespace for the ephemeral environment deployment. The namespace is stored as an environment state value. When it comes time to deprovision the ephemeral environment, the deprovisioning runbook has the namespace available as a variable to delete it.
Each state entry is scoped to project, environment, and optionally a tenant, keeping them isolated. Setting an entry with a key that already exists for the same project, environment, and tenant overwrites the previous value. Keys are case insensitive.
Setting environment state
Set state from a PowerShell or Bash script step using the wrapper functions Octopus provides.
PowerShell
Set-EnvironmentState -Key "namespace" -Value "webstore-pr-482"Bash
set_environmentstate "namespace" "webstore-pr-482"Sensitive values
Mark a value as sensitive to encrypt it at rest and mask it in task logs. Add the -Sensitive switch in PowerShell, or -sensitive as the third argument in Bash.
PowerShell
Set-EnvironmentState -Key "connectionString" -Value "Server=db;Password=s3cret" -SensitiveBash
set_environmentstate "connectionString" "Server=db;Password=s3cret" -sensitiveUsing environment state
Octopus makes each state entry available as a variable named Octopus, where key is the key you set.
To read environment state in a script:
PowerShell
$namespace = $OctopusParameters["Octopus.Environment.State[namespace]"]Bash
namespace=$(get_octopusvariable "Octopus.Environment.State[namespace]")Setting an environment URL
An environment URL is a special type of environment state that gets first-class support in Octopus. It is stored like any other environment state and surfaced as a clickable link in the Octopus Web Portal and available from the API.
Set a URL with the Set-EnvironmentUrl (PowerShell) or set_environmenturl (Bash) function. The first argument is the key that names the URL, and the second is the URL itself.
PowerShell
Set-EnvironmentUrl -Key "Store front" -Url "https://pr-123.example.com"Bash
set_environmenturl "Store front" "https://pr-123.example.com"URLs set this way show as clickable links on the Ephemeral Environments in the project, providing convenient access to the deployed application.
The key used for a URL entry must be unique across all state entries (including non-URLs) for the same project, environment, and tenant. With all state entries, reusing a key will overwrite its value.
Getting URLs from the API
You can fetch the environment URLs from the API, which is useful for AI agents and scripts that need a link to the running app. Add an optional tenantId query parameter for tenanted runs.
GET /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/urlsThe response is an array of name and URL pairs:
[
{ "Name": "Store front", "Url": "https://pr-123.example.com" }
]Limits on environment state
Environment state has the following limits:
- Maximum of 10 environment state entries per combination of project, environment, and optional tenant
- Maximum key length is 100 characters
- Maximum value length is 1000 characters
If any of these limits are exceeded during a deployment or runbook run, the task will fail with an error message explaining how the limit was hit.
Use Octopus variable logging to check if you are nearing your maximum number of environment state entries.
Deleting environment state
If a project, environment, and tenant combination has hit the limit above, delete entries you no longer need to make room for new ones. This function is only available via the HTTP API.
For environment state scoped to a project and environment:
DELETE /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/states/{key}For environment state scoped to a project, environment and tenant:
DELETE /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/states/{key}Use Octopus variable logging to get a list of environment state keys for a project, environment, and optional tenant scope.
Availability
Environment state is rolling out to Octopus Cloud, and will be available to self-hosted customers from version 2026.