Azure DevOps agents - self-hosted - maintenance

September 18, 2023

In continuation to the previous article where we created a self-hosted agent, today we will look into its maintenance aspects

Maintenance job:

Azure DevOps provides an out-of-the-box feature called Maintenance job to clean the stale working directories and repositories

To perform maintenance on the Azure DevOps agent server , go to "Agent Pools" from "Organization Settings".

Select the Default pool where we have self-hosted the agent

In the Settings tab, enable the agent maintenance job

choose the desired settings, especially "Days to keep unused working directory"

Azure Devops agent maintenance

Important Folders and Variables:

It's necessary to know about the following folders in order to debug the agent-related issues

Pipeline.Workspace - The workspace is a directory in which the agent downloads the source,runs steps, and produces outputs

Build.ArtifactStagingDirectory - The local path on the agent where any artifacts are copied before being pushed to their destination. For example: c:\agent_work\1\a

Build.SourcesDirectory - The local path on the agent where the source code files are downloaded. For example: c:\agent_work\1\s

Build.BinariesDirectory - The local path on the agent, it's an output folder for compiled binaries. For example: c:\agent_work\1\b

Clean-up task:

In Microsoft-hosted agents, a new VM is assigned for every job so we do not have to worry about any cleanup activities

however, In self-hosted agents, we may need to use the following task to clean the folders before starting a job

- job: myJob
    clean: outputs | resources | all # what to clean up before the job runs

outputs: Delete Build.BinariesDirectory before running a new job.

resources: Delete Build.SourcesDirectory before running a new job.

all: Delete the entire Pipeline.Workspace directory before running a new job

Common Issues:

  • Permission issues:

If you see the pipeline throwing an error in the lines of "unable to create a file or directory", "the file or directory does not exist" or "ENONT"

The most likely cause is a permission issue, for example, the files may have been created as a root user and the agent user doesn't have the necessary permissions to access those files

  • Disk space issues:

Another common issue is the disk space filling up on the agent server, if this happens you may need to check what are the files being created outside the scope of the maintenance job

For example, you might be using docker and the stale containers and images may need to be cleaned

If you find out that docker is the cause of the space issue, you might have to execute the following command

docker system prune - a shortcut that prunes images, containers, and networks


We saw about the maintenance aspects of the Azure DevOps agents, we will see a comparison between self-hosted and Microsoft-hosted agents in the next week

Thanks for reading, Goodbye until next week!

Profile picture

Written by Thillai Madhavan who lives and works in India. Stay updated by following him on LinkedIn.

All the information on this website - - is published in good faith and for general information purposes only. does not make any warranties about the completeness, reliability and accuracy of this information. Any action you take upon the information you find on this website (, is strictly at your own risk. will not be liable for any losses and/or damages in connection with the use of our website. From our website, you can visit other websites by following hyperlinks to such external sites. While we strive to provide only quality links to useful and ethical websites, we have no control over the content and nature of these sites. These links to other websites do not imply a recommendation for all the content found on these sites. Site owners and content may change without notice and may occur before we have the opportunity to remove a link that may have gone 'bad'. Please be also aware that when you leave our website, other sites may have different privacy policies and terms which are beyond our control. Please be sure to check the Privacy Policies of these sites as well as their "Terms of Service" before engaging in any business or uploading any information. By using our website, you hereby consent to our disclaimer and agree to its terms. Should we update, amend or make any changes to this document, those changes will be prominently posted here
© 2024, OrganicDevOps