From 306c2efc7139359d8f0ba128cf37fda459e20b56 Mon Sep 17 00:00:00 2001 From: Adam McCoy Date: Wed, 19 Aug 2026 10:39:20 +1000 Subject: [PATCH 1/4] Minor edits --- .../environments/environment-state.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/pages/docs/infrastructure/environments/environment-state.md b/src/pages/docs/infrastructure/environments/environment-state.md index 68ce1a1882..8f55abac58 100644 --- a/src/pages/docs/infrastructure/environments/environment-state.md +++ b/src/pages/docs/infrastructure/environments/environment-state.md @@ -1,18 +1,18 @@ --- layout: src/layouts/Default.astro pubDate: 2026-08-07 -modDate: 2026-08-08 +modDate: 2026-08-19 title: Environment state navTitle: Environment state description: Save key/value state during a deployment or runbook run, then read it back in later deployments and runs. navOrder: 30 --- -Environment state lets a deployment or [runbook](/docs/runbooks) run save key/value pairs scoped to the combination of project, environment, and optionally a tenant. Later deployments and runbook runs for the same project and environment can then read those values back. +Environment state lets a deployment or [runbook](/docs/runbooks) 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. -Environment state is useful in scenarios where a value produced during one run needs to be reused later. A common example is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). A provisioning runbook might create a Kubernetes namespace or an application URL that later deployments and the deprovisioning runbook depend on. Recording each value as environment state means Octopus stores it once, so every later run reads it directly instead of re-deriving the value. +A primary use case for environment state is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). For example, a provisioning runbook creates a Kubernetes namespace, Azure resource group, or similar to deploy the application to for testing. The identifiers for these resources are stored as environment state values. When it comes time to deprovision the ephemeral environment the deprovisioning runbook can tear down these resources using the identifiers provided as variables. -Each state entry is scoped to project, environment, and optionally a tenant, so state isn't shared with other projects, environments, or tenants. Setting an entry with a key that already exists for the same project, environment, and tenant overwrites the previous value. Keys are case insensitive. +Each state entry is scoped to project, environment, and optionally a tenant, allowing them to be 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 @@ -58,7 +58,7 @@ set_environmentstate "connectionString" "Server=db;Password=s3cret" -sensitive ## Using environment state -Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]` in later deployment or runbook run, where `key` is the name you set. +Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]`, where `key` is the key you set. Read it from a script: @@ -81,7 +81,7 @@ namespace=$(get_octopusvariable "Octopus.Environment.State[namespace]") ## Setting an environment URL -An environment URL is a type of environment state, but 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. +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. @@ -102,15 +102,15 @@ set_environmenturl "Store front" "https://pr-123.example.com" -URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, so anyone reviewing the environment can open the running app. +URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, providing convenient access to the deployed application. :::div{.hint} -A URL is a special kind of environment state, the key used must be unique across all state entries (including other URLs) for the same project, environment, and tenant. Reusing a key overwrites the value stored under it. +The key used for a URL entry must be unique across all state entries (including non-URLs) for the same project, environment, and tenant. As 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 without reading the task log. Add an optional `tenantId` query parameter for [tenanted](/docs/tenants) runs. +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](/docs/tenants) runs. ```text GET /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/urls @@ -126,8 +126,9 @@ The response is an array of name and URL pairs: ## Limits on environment state -Up to 10 environment state entries can be created for each combination of project, environment and optional tenant. +Environment state entries have 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 From 11d65fe1e73569ecfddf2e51677f84a50c8a4040 Mon Sep 17 00:00:00 2001 From: Adam McCoy Date: Wed, 19 Aug 2026 14:11:41 +1000 Subject: [PATCH 2/4] Tweaks --- .../infrastructure/environments/environment-state.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/pages/docs/infrastructure/environments/environment-state.md b/src/pages/docs/infrastructure/environments/environment-state.md index 8f55abac58..76ce17f035 100644 --- a/src/pages/docs/infrastructure/environments/environment-state.md +++ b/src/pages/docs/infrastructure/environments/environment-state.md @@ -12,7 +12,7 @@ Environment state lets a deployment or [runbook](/docs/runbooks) run store impor A primary use case for environment state is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/ephemeral-environments). For example, a provisioning runbook creates a Kubernetes namespace, Azure resource group, or similar to deploy the application to for testing. The identifiers for these resources are stored as environment state values. When it comes time to deprovision the ephemeral environment the deprovisioning runbook can tear down these resources using the identifiers provided as variables. -Each state entry is scoped to project, environment, and optionally a tenant, allowing them to be 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. +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 @@ -37,7 +37,7 @@ set_environmentstate "namespace" "webstore-pr-482" ### Sensitive values -Mark a value as sensitive to store it encrypted at rest and mask it in task logs. Add the `-Sensitive` switch in PowerShell, or `-sensitive` as the third argument in Bash. +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 @@ -60,7 +60,7 @@ set_environmentstate "connectionString" "Server=db;Password=s3cret" -sensitive Octopus makes each state entry available as a [variable](/docs/projects/variables) named `Octopus.Environment.State[key]`, where `key` is the key you set. -Read it from a script: +To read environment state in a script:
PowerShell @@ -81,7 +81,7 @@ 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. +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. @@ -105,7 +105,7 @@ set_environmenturl "Store front" "https://pr-123.example.com" URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, providing convenient access to the deployed application. :::div{.hint} -The key used for a URL entry must be unique across all state entries (including non-URLs) for the same project, environment, and tenant. As with all state entries, reusing a key will overwrite its value. +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 @@ -126,7 +126,7 @@ The response is an array of name and URL pairs: ## Limits on environment state -Environment state entries have the following limits: +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 From f5b3abecdcec669ea2b3f98aa2a31545d01a47fc Mon Sep 17 00:00:00 2001 From: Adam McCoy Date: Wed, 19 Aug 2026 14:11:49 +1000 Subject: [PATCH 3/4] Does this work? --- .../docs/infrastructure/environments/environment-state.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/infrastructure/environments/environment-state.md b/src/pages/docs/infrastructure/environments/environment-state.md index 76ce17f035..04e76b0234 100644 --- a/src/pages/docs/infrastructure/environments/environment-state.md +++ b/src/pages/docs/infrastructure/environments/environment-state.md @@ -112,7 +112,7 @@ The key used for a URL entry must be unique across all state entries (including 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](/docs/tenants) runs. -```text +```http GET /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/urls ``` @@ -142,13 +142,13 @@ If a project, environment, and tenant combination has hit the limit above, delet For environment state scoped to a project and environment: -```text +```http DELETE /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/states/{key} ``` For environment state scoped to a project, environment and tenant: -```text +```http DELETE /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/states/{key} ``` From 978223085e0d4cf445d024a87059806fde9c3471 Mon Sep 17 00:00:00 2001 From: Adam McCoy Date: Wed, 19 Aug 2026 15:28:39 +1000 Subject: [PATCH 4/4] Review feedback --- .../docs/infrastructure/environments/environment-state.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/infrastructure/environments/environment-state.md b/src/pages/docs/infrastructure/environments/environment-state.md index 04e76b0234..046238b945 100644 --- a/src/pages/docs/infrastructure/environments/environment-state.md +++ b/src/pages/docs/infrastructure/environments/environment-state.md @@ -10,7 +10,7 @@ navOrder: 30 Environment state lets a deployment or [runbook](/docs/runbooks) 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](/docs/infrastructure/ephemeral-environments). For example, a provisioning runbook creates a Kubernetes namespace, Azure resource group, or similar to deploy the application to for testing. The identifiers for these resources are stored as environment state values. When it comes time to deprovision the ephemeral environment the deprovisioning runbook can tear down these resources using the identifiers provided as variables. +A primary use case for environment state is provisioning and deprovisioning [ephemeral environments](/docs/infrastructure/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. @@ -105,7 +105,7 @@ set_environmenturl "Store front" "https://pr-123.example.com" URLs set this way show as clickable links on the [Ephemeral Environments](/docs/projects/ephemeral-environments#environment-urls) in the project, providing convenient access to the deployed application. :::div{.hint} -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. +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