Retention policies for builds, tests, and releases

Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

With retention policies, you can specify the duration to keep your runs, tests, and releases stored in the system. This data is mainly used for audit and tracking. The older runs, tests, and releases get deleted to conserve storage and reduce clutter.

Prerequisites

In order to be able to manage the build and release retention policies, you will need to be part of one of the following built-in groups:

  • Contributors.
  • Build Admins.
  • Project Admins.
  • Release Admins.

To manage your test result, you must have one of the following subscriptions:

Or, configure Basic + Test Plans access level.

See Testing access by user role.

Build retention policies

In most cases you don't need to retain completed runs longer than a certain number of days. Using retention policies, you can control how many days you want to keep each run before deleting it.

Along with defining how many days to retain runs, you can also decide the minimum number of runs that should be kept for each pipeline.

As an author of a build pipeline, you can customize retention policies on the gear icon Settings tab of your project's settings.

You can use the Copy Files task to save your build and artifact data for longer than what is set in the retention policies. The Copy Files task is preferable to the Publish Build Artifacts task because data saved with the Publish Build Artifacts task will get periodically cleaned up and deleted.

- task: CopyFiles@2
  displayName: 'Copy Files to: \\mypath\storage\$(Build.BuildNumber)'
  inputs:
    SourceFolder: '$(Build.SourcesDirectory)'
    Contents: '_buildOutput/**'
    TargetFolder: '\\mypath\storage\$(Build.BuildNumber)'

You can also customize these policies on a branch-by-branch basis if you are building from Git repositories.

Global build retention policy

You can specify build retention policy defaults and maximums for a project collection. You can also specify when builds are permanently destroyed (removed from the Deleted tab in the build explorer).

  • TFS 2017 and newer: https://{your_server}/tfs/DefaultCollection/_admin/_buildQueue
  • TFS 2015.3: http://{your_server}:8080/tfs/DefaultCollection/_admin/_buildQueue

  • TFS 2015 RTM: http://{your_server}:8080/tfs/DefaultCollection/_admin/_buildQueue#_a=settings

The maximum retention policy sets the upper limit for how long runs can be retained for all build pipelines. Authors of build pipelines cannot configure settings for their definitions beyond the values specified here.

The default retention policy sets the default retention values for all the build pipelines. Authors of build pipelines can override these values.

The Permanently destroy releases helps you keep the runs for a certain period of time after they are deleted. This policy cannot be overridden in individual build pipelines.

Git repositories

If your repository type is one of the following, you can define multiple retention policies with branch filters:

  • Azure Repos Git or TFS Git.
  • GitHub.
  • Other/external Git.

For example, your team may want to keep:

  • User branch builds for five days, with a minimum of a single successful or partially successful build for each branch.
  • Master and feature branch builds for 10 days, with a minimum of three successful or partially successful builds for each of these branches. You exclude a special feature branch that you want to keep for a longer period of time.
  • Builds from the special feature branch and all other branches for 15 days, with a minimum of a single successful or partially successful build for each branch.

The following example retention policy for a build pipeline meets the above requirements:

define git retention policies

When specifying custom policies for each pipeline, you cannot exceed the maximum limits set by administrator.

Clean up pull request builds

If you protect your Git branches with pull request builds, then you can use retention policies to automatically delete the completed builds. To do it, add a policy that keeps a minimum of 0 builds with the following branch filter:

  refs/pull/*

retention-policy-for-pull-request-builds

TFVC and Subversion repositories

For TFVC and Subversion repository types you can modify a single policy with the same options shown above.

Policy order

When the system is purging old builds, it evaluates each build against the policies in the order you have specified. You can drag and drop a policy lower or higher in the list to change this order.

The "All" branches policy is automatically added as the last policy in the evaluation order to enforce the maximum limits for all other branches.

define git retention policy max shown in pipeline

What parts of the run get deleted

When the retention policies mark a build for deletion, you can control which information related to the build is deleted:

  • Build record: You can choose to delete the entire build record or keep basic information about the build even after the build is deleted.
  • Source label: If you label sources as part of the build, then you can choose to delete the tag (for Git) or the label (for TFVC) created by a build.
  • Automated test results: You can choose to delete the automated test results associated with the build (for example, results published by the Publish Test Results build task).

The following information is deleted when a build is deleted:

  • Logs
  • Published artifacts
  • Published symbols

The following information is deleted when a run is deleted:

  • Logs
  • All artifacts
  • All symbols
  • Binaries
  • Test results
  • Run metadata

When are runs deleted

Your retention policies are processed once per day. The timing of this process varies because we spread the work throughout the day for load-balancing purposes. There is no option to change this process.

Your retention policies run every day at 3:00 A.M. UTC. There is no option to change this process.

Delete a run

You can delete runs using the context menu on the Pipeline run details page.

Note

If any retention policies currently apply to the run, they must be removed before the run can be deleted. For instructions, see Pipeline run details - delete a run.

delete a run

Release retention policies

The release retention policies for a release pipeline determine how long a release and the run linked to it are retained. Using these policies, you can control how many days you want to keep each release after it has been last modified or deployed and the minimum number of releases that should be retained for each pipeline.

The retention timer on a release is reset every time a release is modified or deployed to a stage. The minimum number of releases to retain setting takes precedence over the number of days. For example, if you specify to retain a minimum of three releases, the most recent three will be retained indefinitely - irrespective of the number of days specified. However, you can manually delete these releases when you no longer require them.

As an author of a release pipeline, you can customize retention policies for releases of your pipeline on the Retention tab.

The retention policy for YAML and build pipelines is the same. You can see your pipeline's retention settings in Project Settings for Pipelines in the Settings section.

You can also customize these policies on a stage-by-stage basis.

Global release retention policy

If you are using an on-premises Team Foundation Server, you can specify release retention policy defaults and maximums for a project. You can also specify when releases are permanently destroyed (removed from the Deleted tab in the build explorer).

If you are using Azure Pipelines, you can view but not change these settings for your project.

Global release retention policy settings can be managed from the Release settings of your project:

  • Azure Pipelines: https://dev.azure.com/{organization}/{project}/_settings/release?app=ms.vss-build-web.build-release-hub-group
  • On-premises: https://{your_server}/tfs/{collection_name}/{project}/_admin/_apps/hub/ms.vss-releaseManagement-web.release-project-admin-hub

The maximum retention policy sets the upper limit for how long releases can be retained for all release pipelines. Authors of release pipelines cannot configure settings for their definitions beyond the values specified here.

The default retention policy sets the default retention values for all the release pipelines. Authors of build pipelines can override these values.

The destruction policy helps you keep the releases for a certain period of time after they are deleted. This policy cannot be overridden in individual release pipelines.

Note

In TFS, release retention management is restricted to specifying the number of days, and this is available only in TFS 2015.3 and newer.

Stage-specific retention policies

You may want to retain more releases that have been deployed to specific stages. For example, your team may want to keep:

  • Releases deployed to Production stage for 60 days, with a minimum of three last deployed releases.
  • Releases deployed to Pre-production stage for 15 days, with a minimum of one last deployed release.
  • Releases deployed to QA stage for 30 days, with a minimum of two last deployed releases.
  • Releases deployed to Dev stage for 10 days, with a minimum of one last deployed release.

The following example retention policy for a release pipeline meets the above requirements:

Configuring the release retention setting for a release pipeline

In this example, if a release that is deployed to Dev is not promoted to QA for 10 days, it is a potential candidate for deletion. However, if that same release is deployed to QA eight days after being deployed to Dev, its retention timer is reset, and it is retained in the system for another 30 days.

When specifying custom policies per pipeline, you cannot exceed the maximum limits set by administrator.

Interaction between build and release retention policies

The build linked to a release has its own retention policy, which may be shorter than that of the release. If you want to retain the build for the same period as the release, set the Retain associated artifacts checkbox for the appropriate stages. This overrides the retention policy for the build, and ensures that the artifacts are available if you need to redeploy that release.

When you delete a release pipeline, delete a release, or when the retention policy deletes a release automatically, the retention policy for the associated build will determine when that build is deleted.

Note

In TFS, interaction between build and release retention is available in TFS 2017 and newer.

Manual test-runs retention policies

To delete manual test results after a specific number of days, set the retention limit at the project level. Azure DevOps keeps manual test results related to builds, even after you delete those builds. That way, build policies don't delete your test results before you can analyze the data.

  1. Sign into your Azure DevOps. You'll need at least project administrator permissions.

  2. Go to your project and then select gear icon project settings at the bottom of the page.

project settings

  1. In the Retention page under the Test section, select a limit for how long you want to keep manual test data.

manual tests retention policies

Automated test-runs retention policies

Builds automated test results

By default, Azure DevOps keeps automated test results related to builds only as long as you keep those builds. To keep test results after you delete your builds, edit the build retention policy. If you use Git for version control, you can specify how long to keep automated test results based on the branch.

  1. Sign into Azure DevOps. You'll need at least build level permissions to edit build pipelines.

  2. Go to your project and then select gear icon project settings at the bottom of the page.

project settings

  1. Select gear icon Settings under Pipelines and modify your retention policies.

project settings

Other automated test results

To clean up automated test results that are left over from deleted builds or test results that aren't related to builds, for example, results published from external test systems, set the retention limits at the project level as shown in the Manual test-runs retention policies

Artifact retention

Setting a Build.Cleanup capability on agents will cause the pool's cleanup jobs to be directed to just those agents, leaving the rest free to do regular work. When a pipeline run is deleted, artifacts stored outside of Azure DevOps are cleaned up through a job run on the agents. When the agent pool gets saturated with cleanup jobs, this can cause a problem. The solution to that is to designate a subset of agents in the pool that are the cleanup agents. If any agents have Build.Cleanup set, only those agents will run the cleanup jobs, leaving the rest of the agents free to continue running pipeline jobs.

FAQ

Are manual test results deleted?

No

If I mark a run or a release to be retained indefinitely, does the retention policy still apply?

No. Neither the pipeline's retention policy nor the maximum limits set by the administrator are applied when you mark an individual run or release to be retained indefinitely. It will remain until you stop retaining it indefinitely.

How do I specify that runs deployed to production will be retained longer?

Customize the retention policy on the release pipeline. Specify the number of days that releases deployed to production must be retained. In addition, indicate that runs associated with that release are to be retained. This will override the run retention policy.

I did not mark runs to be retained indefinitely. However, I see a large number of runs being retained. How can I prevent this?

Runs that are deployed as part of releases are also governed by the release retention policy. Customize the release retention policy as explained above.

Are automated test results that are published as part of a release retained until the release is deleted?

Test results published within a stage of a release are associated with both the release and the run. These test results are retained as specified by the retention policy configured for the run and for the test results. If you are not deploying Team Foundation or Azure Pipelines Build, and are still publishing test results, the retention of these results is governed by the retention settings of the release they belong to.