Configuring lifecycle retention policy

How retention policies work with lifecycle phases

You can set individual retention policies to phases. This gives you much more control over environments, such as never deleting from production but having a strict rigorous deletion from your development environment.

But how does it work? For a release we determine what phase it is currently in. So if a release is created and no deployments have been done, the default lifecycle retention policy is the active setting for that release. When it is then deployed to the first phase, that retention policy becomes the active setting for the release, and so on. So when the release hits the production phase, and is set to keep all, that release will be kept, as will any deployments done to any environment of that release.

If you have a release retention policy for a project that has a final phase of keep all releases, once the release enters that phase it will never be deleted. But if you have a release that has not yet deployed to any environments in the final phase, and is set to only keep the last 3 releases, then the release will be deleted when it becomes the 4th release of the project that has not yet been deployed to any final phase environment (unless it is still on the dashboard).

Example lifecycle retention policy task

In this section we walk through what’s deleted for an example project when the retention policy task runs. Consider a project that has the following lifecycle defined:

It contains two phases, both are set to keep the last 3 releases.

The project has 15 releases, of which:

• 0.0.10 through 0.0.15 have not been deployed to any environment.
• 0.0.7 through 0.0.9 are deployed to Staging.
• 0.0.1 through 0.0.6 are deployed to both Staging and Production.

When the retention policy runs for this lifecycle, it keeps a count of both undeployed releases it finds, as well as a separate count for releases per phase.

For a release to be deleted, the count must be greater than the required number for each phase the release has been deployed to. In this example, release 0.0.2 is the fourth release kept for Staging, but only the third for Production, so it will be kept.

Each phase defined in this lifecycle will keep a maximum of 5 releases:

• 1 release for the current dashboard version.
• 1 release for the dashboard version’s rollback.
• The last 3 releases, as configured in the phase.

Undeployed releases will simply keep the number we have selected and no more. When the retention policy task runs, 4 releases are deleted:

                    |     == Success: Apply policy for Retention Policy Examples to Sample Project Default ==
13:51:03   Info     |       Retention Policy Examples/[Default] - Project name: Sample Project
                    |       Retention Policy Examples/[Default] - Channel name: Default
                    |       Retention Policy Examples/[Default] - Policy: Last 3 items
                    |       Retention Policy Examples/[Default] - Phase 1. Staging: Last 3 items (inherited)
                    |       Retention Policy Examples/[Default] - Phase 2. Production: Last 3 items (inherited)
13:51:03   Info     |       Retention Policy Examples/[Default] - Releases currently on the dashboard: 0.0.9, 0.0.6
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.15 is in phase Staging, with a policy of Last 3 items; it will be kept. Reason: Undeployed, kept so far = 0
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.14 is in phase Staging, with a policy of Last 3 items; it will be kept. Reason: Undeployed, kept so far = 1
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.13 is in phase Staging, with a policy of Last 3 items; it will be kept. Reason: Undeployed, kept so far = 2
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.12 is in phase Staging, with a policy of Last 3 items; it will be deleted. Reason: Undeployed, but 3 of 3 have been kept
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.11 is in phase Staging, with a policy of Last 3 items; it will be deleted. Reason: Undeployed, but 3 of 3 have been kept
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.10 is in phase Staging, with a policy of Last 3 items; it will be deleted. Reason: Undeployed, but 3 of 3 have been kept
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.9 is on the dashboard, so it will be kept
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.8 is the previous release for a release on the dashboard, so it will be kept to allow rollback
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.7 has progressed through phase Staging, with a policy of Last 3 items, but has not yet been deployed to phase Production; it will be kept. Reason: Deployed to: Staging, kept so far = 0
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.6 is on the dashboard, so it will be kept
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.5 is the previous release for a release on the dashboard, so it will be kept to allow rollback
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.4 is in phase Production, with a policy of Last 3 items; it will be kept. Reason: Deployed to: Staging, kept so far = 1; Deployed to: Production, kept so far = 0
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.3 is in phase Production, with a policy of Last 3 items; it will be kept. Reason: Deployed to: Staging, kept so far = 2; Deployed to: Production, kept so far = 1
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.2 is in phase Production, with a policy of Last 3 items; it will be kept. Reason: Deployed to: Staging, but 3 of 3 have been kept; Deployed to: Production, kept so far = 2
13:51:03   Info     |       Retention Policy Examples/[Default] - Release 0.0.1 is in phase Production, with a policy of Last 3 items; it will be deleted. Reason: Deployed to: Staging, but 3 of 3 have been kept; Deployed to: Production, but 3 of 3 have been kept
13:51:03   Verbose  |       Delete release 0.0.12
13:51:03   Verbose  |       Delete release 0.0.11
13:51:03   Verbose  |       Delete release 0.0.10
13:51:03   Verbose  |       Delete release 0.0.1

Set release retention policies

Under Deploy ➜ Manage ➜ Lifecycles you select the Lifecycle you want to define or edit your retention policy for:

Each phase will inherit the retention policy from the above phase, but this is something you can change by expanding the Retention Policy panel.

Releases determines what is kept on the Octopus Server, and Files on Tentacle determines what files are kept on the Tentacle.

In Octopus Server, you can keep all, or select a number of releases to keep.

Alternatively, you can specify a number of days worth of releases and files to keep.

Updating the default retention policy

You can update the default retention settings used by lifecycle under Manage ➜ Retention ➜ Release Retention.

Inherited retention policies

As mentioned above, any phase that does not have a retention policy set will inherit its retention policy in the following priority:

1. From the latest previous phase with a custom retention policy
2. From the lifecycle retention policy

This can be observed in the following retention policy setup:

• Lifecycle: Keep 3 Releases
• Phase 1 (Dev): Inherit (Keep 3 Releases)
• Phase 2 (Test): Inherit (Keep 3 Releases)
• Phase 3 (Staging): Keep 5 Releases
• Phase 4 (Prod): Inherit (Keep 5 Releases)

Note how Dev and Test inherit their policies from the lifecycle retention policy as there is no previous phase with a custom retention policy. As Prod comes after Staging, a phase which has a custom retention policy, Prod inherits its retention policy from Staging instead.

Phases prioritize retention policies from the latest previous phase over the lifecycle retention policy as later phases tend to be treated more seriously. The more serious a phase is, the more the retention policy matters. The final phases are more likely to be production environments, and therefore once a release reaches this point you will want to keep more of them.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Monday, November 3, 2025