Document retention support in project templates

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,9 +111,13 @@ 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)
 :::
 
-:::div{.warning}
-While retention policies can be configured in project template lifecycles, these aren't yet fully supported.
-:::
+### 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.
+
+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.
 
 ## Parameters
 
@@ -213,3 +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 `2026.4.7884`.

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.

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,16 @@ 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 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.
+
+:::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
 
 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: