Set retention policies for builds, releases, and tests
TFS 2017 | TFS 2015
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.
Retention policies let you set how long to keep runs, releases, and tests stored in the system. To save storage space, you want to delete older runs, tests, and releases.
The following retention policies are available in Azure DevOps in your Project settings:
- Pipeline - Set how long to keep artifacts, symbols, attachments, runs, and pull request runs.
- Release (classic) - Set whether to save builds and view the default and maximum retention settings.
- Test - Set how long to keep automated and manual test runs, results, and attachments.
Note
If you are using an on-premises server, you can also specify retention policy defaults for a project and when releases are permanently destroyed. Learn more about release retention later in this article.
Prerequisites
By default, members of the Contributors, Build Admins, Project Admins, and Release Admins groups can manage retention policies.
To manage test results, you must have one of the following subscriptions:
You can also buy monthly access to Azure Test Plans and assign the Basic + Test Plans access level. See Testing access by user role.
Set run 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.
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
When are runs deleted
Your retention policies run every day at 3:00 A.M. UTC. There is no option to change the time the policies run.
Automatically set retention lease on pipeline runs
Retention leases are used to manage the lifetime of pipeline runs beyond the configured retention periods. Retention leases can be added or deleted on a pipeline run by calling the Lease API. This API can be invoked within the pipeline using a script and using predefined variables for runId and definitionId.
A retention lease can be added on a pipeline run for a specific period. For example, a pipeline run which deploys to a test environment can be retained for a shorter duration while a run deploying to production environment can be retained longer.
Manually set retention lease on pipeline runs
You can manually set a pipeline run to be retained using the More actions menu on the Pipeline run details page.
Set release retention policies
The release retention policies for a classic 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. See FAQ below for more details about how release retention works.
As an author of a release pipeline, you can customize retention policies for releases of your pipeline on the Retention tab.
You can also learn how to customize these policies on a stage-by-stage basis later in this article.
Global release retention policy
If you are using an on-premises Team Foundation Server or Azure DevOps 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 DevOps Services, you can view but not change these settings for your project.
Global release retention policy settings can be managed from the Release retention settings of your project:
- Azure DevOps Services:
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:
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.
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 2015.3:
http://{your_server}:8080/tfs/DefaultCollection/_admin/_buildQueueTFS 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.
- Main 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:
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/*
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.
FAQ
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?
If you use classic releases to deploy to production, then 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.
If you use multi-stage YAML pipelines to production, the only retention policy you can configure is in the project settings. You cannot customize retention based on the environment to which the build is deployed.
I did not mark runs to be retained indefinitely. However, I see a large number of runs being retained. How can I prevent this?
This could be for one of the following reasons:
- The runs are marked by someone in your project to be retained indefinitely.
- The runs are consumed by a release, and the release holds a retention lock on these runs. Customize the release retention policy as explained above.
If you believe that the runs are no longer needed or if the releases have already been deleted, then you can manually delete the runs.
How does 'minimum releases to keep' setting work?
Minimum releases to keep are defined at stage level. It denotes that Azure DevOps will always retain the given number of last deployed releases for a stage even if the releases are out of retention period. A release will be considered under minimum releases to keep for a stage only when the deployment started on that stage. Both successful and failed deployments are considered. Releases pending approval are not considered.
How is retention period decided when release is deployed to multiple stages having different retention period?
Final retention period is decided by considering days to retain settings of all the stages on which release is deployed and taking max days to keep among them. Minimum releases to keep is governed at stage level and do not change based on release deployed to multiple stages or not. Retain associated artifacts will be applicable when release is deployed to a stage for which it is set true.
I deleted a stage for which I have some old releases. What retention will be considered for this case?
As the stage is deleted, so the stage level retention settings are not applicable now. Azure DevOps will fall back to project level default retention for such case.
My organization requires us to retain builds and releases longer than what is allowed in the settings. How can I request a longer retention?
The only way to retain a run or a release longer than what is allowed through retention settings is to manually mark it to be retained indefinitely. There is no way to configure a longer retention setting. You can also explore the possibility of using the REST APIs in order to download information and artifacts about the runs and upload them to your own storage or artifact repository.
I lost some runs. Is there a way to get them back?
If you believe that you have lost runs due to a bug in the service, create a support ticket immediately to recover the lost information. If a build definition was manually deleted more than a week earlier, it will not be possible to recover it. If the runs were deleted as expected due to a retention policy, it will not be possible to recover the lost runs.
How do I use the Build.Cleanup capability of agents?
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.
What happens to file share Artifacts when the build is deleted
When a build with file share Artifacts is deleted, a new build task is queued on a build agent to clean up those files. An agent is picked to perform this task based on the following criteria:
Is there an agent with Build.Cleanup capability available?
Is the agent that ran the build available?
Is an agent from the same pool available?
Is an agent from a similar pool available?
Is any agent available?
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 retained as specified by the retention policy configured for the test results. The test results do not get retained until the release is retained. If you need the test results as long as the release, set the retention settings for automated test runs in the Project settings accordingly to Never delete. This makes sure the test results are deleted only when the release is deleted.
Are manual test results deleted?
No. Manual test results are not deleted.