From d60bd0749ec125b0916107df27693ae750ac1b7b Mon Sep 17 00:00:00 2001 From: clairehuizenga Date: Mon, 12 Oct 2026 11:53:03 +1100 Subject: [PATCH 1/6] Document retention support in project templates Release and Tentacle file retention policies set on project template lifecycles are now applied to templated projects. Previously they had no effect. --- .../templates/project-templates/index.md | 13 +++++++++++-- .../templates/project-templates/troubleshooting.md | 13 +++++++++++-- .../project-templates/using-project-templates.md | 10 +++++++++- 3 files changed, 31 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/platform-hub/templates/project-templates/index.md b/src/pages/docs/platform-hub/templates/project-templates/index.md index 15b0f22a66..064b16ac26 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/index.md +++ b/src/pages/docs/platform-hub/templates/project-templates/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2026-03-05 -modDate: 2026-09-21 +modDate: 2026-10-12 title: Project templates subtitle: An overview of project templates icon: fa-solid fa-layer-group @@ -111,10 +111,18 @@ Every project template comes with a default lifecycle. This uses the same conven ![Lifecycles in project templates](/docs/img/platform-hub/project-templates/project-templates-lifecycles.png) ::: +### Retention policies + +You can set [release and Tentacle file retention policies](/docs/administration/retention-policies) on each lifecycle and phase in a project template. Octopus applies them to every templated project that uses the template, per channel and lifecycle. + :::div{.warning} -While retention policies can be configured in project template lifecycles, these aren't yet fully supported. +If you set retention policies on project template lifecycles before Octopus started applying them, the next retention run will apply those policies. Releases and Tentacle files that were previously kept may be deleted, and deleted releases can't be recovered. Review your project template retention policies before upgrading. ::: +Retention policies in project templates can't exceed your license's retention limits. [VERIFY: whether a docs page explains license retention limits that this sentence should link to — needs: confirmation from Sea Dragon or the licensing docs owner] If a policy exceeds the limits, Octopus shows a warning icon on **Lifecycles** and a message on the policy. You can't save or publish the template until you bring the policy within the limits. + +If your license changes after you've published a template version, Octopus doesn't rewrite that version. Instead, each retention run uses the lower of the template's policy and your license limit. Deployments aren't affected. + ## Parameters [Parameters](/docs/platform-hub/templates/parameters) let you define the inputs a user must supply when they create a project from the template. They're the mechanism for making a template flexible. Rather than hardcoding values that differ between teams or spaces, you expose them as parameters. @@ -213,3 +221,4 @@ Project templates are in Public Preview and we're actively shaping how the featu ## Version notes - [Channels](#channels) and [Lifecycles](#lifecycles) in Project Templates are available from Octopus Server version `2026.4.4005`. +- Retention policies in project template lifecycles are applied from Octopus Server version [PLACEHOLDER: exact build number — needs: the release build from Sea Dragon]. diff --git a/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md b/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md index d5c584d69f..be37440836 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md +++ b/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2026-03-05 -modDate: 2026-09-21 +modDate: 2026-10-12 title: Troubleshooting subtitle: Known issues and limitations for project templates icon: fa-solid fa-layer-group @@ -20,7 +20,6 @@ Project templates are in Public Preview. The feature is still evolving and stand Project templates are in Public Preview. The following features are not yet supported and are planned for future releases: - Ephemeral environments, including ephemeral environment channels -- Retention policies on templated project releases (you can configure them, but they have no effect) - Cloud target discovery on steps (see below) - Cloning a project template through the Octopus UI - Creating and managing project templates through the REST API, CLI, or Terraform provider @@ -40,6 +39,16 @@ Support for configuring project triggers and runbook scheduled triggers for temp ::: +## Retention isn't applied to a templated project + +Octopus skips retention for a templated project when its environment parameter values don't make a valid lifecycle. This happens when: + +- A phase's environment parameter has no environments +- A phase's environment parameter isn't set to a valid environment +- The same environment appears in more than one phase + +While retention is skipped, Octopus keeps the project's releases and Tentacle files. After you fix the environment parameter values in the templated project, the next retention run applies the policies. + ## Deployment freezes When selecting projects for a global deployment freeze, filtering by environment may not show all templated projects that use the selected environment. diff --git a/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md b/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md index aab7d158f4..38a31e0e35 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md +++ b/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2026-03-16 -modDate: 2026-09-21 +modDate: 2026-10-12 title: Templated projects subtitle: How to create and manage projects from a project template icon: fa-solid fa-layer-group @@ -84,6 +84,14 @@ The environments a channel can deploy to depend on the environment parameter val ![Channels in a templated project](/docs/img/platform-hub/project-templates/templated-project-channel.png) ::: +## Retention policies + +A templated project uses the retention policies set on its template's lifecycles. Octopus uses the environment parameter values you set in the project to work out which environments belong to each lifecycle phase. + +If the template's policies exceed your license's retention limits, Octopus limits them to match your license and shows a message on the **Channels** page. + +For Config as Code projects, Octopus reads environment parameter values from the project's default branch for every release, including releases created from other branches. + ## Template updates When a new version of the template is published, you'll receive the update. How and when it's applied depends on the versioning preferences you've set: From 238e92780c08ba422b5282f51bcc131d902c0829 Mon Sep 17 00:00:00 2001 From: clairehuizenga Date: Mon, 12 Oct 2026 11:58:45 +1100 Subject: [PATCH 2/6] Link license retention limits for project templates --- .../docs/platform-hub/templates/project-templates/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/platform-hub/templates/project-templates/index.md b/src/pages/docs/platform-hub/templates/project-templates/index.md index 064b16ac26..aa7a17a2fc 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/index.md +++ b/src/pages/docs/platform-hub/templates/project-templates/index.md @@ -119,7 +119,7 @@ You can set [release and Tentacle file retention policies](/docs/administration/ If you set retention policies on project template lifecycles before Octopus started applying them, the next retention run will apply those policies. Releases and Tentacle files that were previously kept may be deleted, and deleted releases can't be recovered. Review your project template retention policies before upgrading. ::: -Retention policies in project templates can't exceed your license's retention limits. [VERIFY: whether a docs page explains license retention limits that this sentence should link to — needs: confirmation from Sea Dragon or the licensing docs owner] If a policy exceeds the limits, Octopus shows a warning icon on **Lifecycles** and a message on the policy. You can't save or publish the template until you bring the policy within the limits. +Retention policies in project templates can't exceed [your license's retention limits](/docs/best-practices/octopus-administration/ongoing-maintenance#octopus-cloud). If a policy exceeds the limits, Octopus shows a warning icon on **Lifecycles** and a message on the policy. You can't save or publish the template until you bring the policy within the limits. If your license changes after you've published a template version, Octopus doesn't rewrite that version. Instead, each retention run uses the lower of the template's policy and your license limit. Deployments aren't affected. From 28305db178237eaf4a4b1c8095d55549fd238523 Mon Sep 17 00:00:00 2001 From: clairehuizenga Date: Mon, 12 Oct 2026 12:00:12 +1100 Subject: [PATCH 3/6] Remove retention upgrade warning from project templates --- .../docs/platform-hub/templates/project-templates/index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/pages/docs/platform-hub/templates/project-templates/index.md b/src/pages/docs/platform-hub/templates/project-templates/index.md index aa7a17a2fc..dd782a9911 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/index.md +++ b/src/pages/docs/platform-hub/templates/project-templates/index.md @@ -115,10 +115,6 @@ Every project template comes with a default lifecycle. This uses the same conven You can set [release and Tentacle file retention policies](/docs/administration/retention-policies) on each lifecycle and phase in a project template. Octopus applies them to every templated project that uses the template, per channel and lifecycle. -:::div{.warning} -If you set retention policies on project template lifecycles before Octopus started applying them, the next retention run will apply those policies. Releases and Tentacle files that were previously kept may be deleted, and deleted releases can't be recovered. Review your project template retention policies before upgrading. -::: - Retention policies in project templates can't exceed [your license's retention limits](/docs/best-practices/octopus-administration/ongoing-maintenance#octopus-cloud). If a policy exceeds the limits, Octopus shows a warning icon on **Lifecycles** and a message on the policy. You can't save or publish the template until you bring the policy within the limits. If your license changes after you've published a template version, Octopus doesn't rewrite that version. Instead, each retention run uses the lower of the template's policy and your license limit. Deployments aren't affected. From 2f927ea8bda667b481c19c7de525467e5e2bd0f1 Mon Sep 17 00:00:00 2001 From: clairehuizenga Date: Tue, 13 Oct 2026 14:55:21 +1100 Subject: [PATCH 4/6] pr feedback --- .../docs/platform-hub/templates/project-templates/index.md | 2 +- .../templates/project-templates/using-project-templates.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/platform-hub/templates/project-templates/index.md b/src/pages/docs/platform-hub/templates/project-templates/index.md index dd782a9911..67b55e9317 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/index.md +++ b/src/pages/docs/platform-hub/templates/project-templates/index.md @@ -115,7 +115,7 @@ Every project template comes with a default lifecycle. This uses the same conven You can set [release and Tentacle file retention policies](/docs/administration/retention-policies) on each lifecycle and phase in a project template. Octopus applies them to every templated project that uses the template, per channel and lifecycle. -Retention policies in project templates can't exceed [your license's retention limits](/docs/best-practices/octopus-administration/ongoing-maintenance#octopus-cloud). If a policy exceeds the limits, Octopus shows a warning icon on **Lifecycles** and a message on the policy. You can't save or publish the template until you bring the policy within the limits. +Retention policies in project templates can't exceed [your license's retention limits](/docs/best-practices/octopus-administration/ongoing-maintenance#octopus-cloud). These limits only apply to Octopus Cloud. Self-hosted Octopus Server has no limits. If a policy exceeds the limits, Octopus shows a warning icon on **Lifecycles** and a message on the policy. You can't save or publish the template until you bring the policy within the limits. If your license changes after you've published a template version, Octopus doesn't rewrite that version. Instead, each retention run uses the lower of the template's policy and your license limit. Deployments aren't affected. diff --git a/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md b/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md index 38a31e0e35..028ccdd91a 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md +++ b/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md @@ -88,9 +88,11 @@ The environments a channel can deploy to depend on the environment parameter val A templated project uses the retention policies set on its template's lifecycles. Octopus uses the environment parameter values you set in the project to work out which environments belong to each lifecycle phase. -If the template's policies exceed your license's retention limits, Octopus limits them to match your license and shows a message on the **Channels** page. +On Octopus Cloud if the template's policies exceed your license's retention limits, Octopus limits them to match your license and shows a message on the **Channels** page. +:::div{.hint} For Config as Code projects, Octopus reads environment parameter values from the project's default branch for every release, including releases created from other branches. +::: ## Template updates From 77fcc24f069ca37753611650c7b6da4efbe8e626 Mon Sep 17 00:00:00 2001 From: clairehuizenga Date: Tue, 13 Oct 2026 14:58:12 +1100 Subject: [PATCH 5/6] wording change --- .../templates/project-templates/using-project-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md b/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md index 028ccdd91a..f91e4fe1a6 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md +++ b/src/pages/docs/platform-hub/templates/project-templates/using-project-templates.md @@ -86,7 +86,7 @@ The environments a channel can deploy to depend on the environment parameter val ## Retention policies -A templated project uses the retention policies set on its template's lifecycles. Octopus uses the environment parameter values you set in the project to work out which environments belong to each lifecycle phase. +A templated project uses the retention policies set on its template's lifecycles. Octopus uses the environment parameter values you set in the project to determine which environments belong to each lifecycle phase. On Octopus Cloud if the template's policies exceed your license's retention limits, Octopus limits them to match your license and shows a message on the **Channels** page. From 65491b66a118e3a3c91aa657c48ef1ec84b05afa Mon Sep 17 00:00:00 2001 From: clairehuizenga Date: Fri, 16 Oct 2026 15:40:22 +1100 Subject: [PATCH 6/6] add version --- .../docs/platform-hub/templates/project-templates/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/docs/platform-hub/templates/project-templates/index.md b/src/pages/docs/platform-hub/templates/project-templates/index.md index 67b55e9317..c2294f1b1c 100644 --- a/src/pages/docs/platform-hub/templates/project-templates/index.md +++ b/src/pages/docs/platform-hub/templates/project-templates/index.md @@ -217,4 +217,4 @@ Project templates are in Public Preview and we're actively shaping how the featu ## Version notes - [Channels](#channels) and [Lifecycles](#lifecycles) in Project Templates are available from Octopus Server version `2026.4.4005`. -- Retention policies in project template lifecycles are applied from Octopus Server version [PLACEHOLDER: exact build number — needs: the release build from Sea Dragon]. +- Retention policies in project template lifecycles are applied from Octopus Server version `2026.4.7884`.