From 37b1bc6a1951506ef54309cceb379b5f695698a6 Mon Sep 17 00:00:00 2001 From: caitlynstocker Date: Tue, 18 Aug 2026 12:00:27 +1000 Subject: [PATCH 1/2] Environment state docs updates --- .../environments/environment-state.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/pages/docs/infrastructure/environments/environment-state.md b/src/pages/docs/infrastructure/environments/environment-state.md index 14052902fb..9163ef3138 100644 --- a/src/pages/docs/infrastructure/environments/environment-state.md +++ b/src/pages/docs/infrastructure/environments/environment-state.md @@ -124,6 +124,35 @@ 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. + +- 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](/docs/support/how-to-turn-on-variable-logging-and-export-the-task-log) 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. Deleting is API-only. + +For environment state scoped to a project and environment: + +```text +DELETE /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/states/{key} +``` + +For environment state scoped to a project, environment and tenant: + +```text +DELETE /api/spaces/{spaceId}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/states/{key} +``` + +Use [Octopus variable logging](/docs/support/how-to-turn-on-variable-logging-and-export-the-task-log) 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.3`. From a8bd57c4bc83babdebda01d66a49721a09e85256 Mon Sep 17 00:00:00 2001 From: caitlynstocker Date: Tue, 18 Aug 2026 14:40:45 +1000 Subject: [PATCH 2/2] Small additions on review --- .../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 9163ef3138..68ce1a1882 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 save key/va 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. -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. +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. ## Setting environment state @@ -137,7 +137,7 @@ Use [Octopus variable logging](/docs/support/how-to-turn-on-variable-logging-and ## 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. Deleting is API-only. +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: