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..c2294f1b1c 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,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`. 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..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 @@ -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: