Azure DevOps directories and folders Cheat-Sheet
Introduction
You must have noticed if you are new to Azure DevOps, or even if you have been using it for not so long, that not only the documentation is not that rich, but it’s so confusing.
What I personally have always found confusing, is tasks and the predefined variables that represent the default folders associated to them.
In this CU (stands for Continuously Updated, just made it up, not so funny, I know) article, I will try provide a simple straightforward cheat sheet that will cover the most used directories when setting a build pipeline.
Example : task that may cause confusion
Let’s take this example, the Publish Pipeline Artifacts task. Its documentation article doesn’t cite in anywhere where this task publishes the actual artifacts. Not only that it doesn’t, it even misses some of the task’s properties. Here’s what the actual documentation shows :
What is actually available in the Azure DevOps yaml pipeline (at least until the current date) :
You can never know from the documentation where does this task publish the artifacts, or if you have the possibility to choose between different targets (Well… targets, the word itself causes confusion as we will see).
Publish Pipeline artifacts task is a successor of the Publish Build Artifacts task, which is somehow better documented. However, Microsoft recommends upgrading to the first one because it’s faster.
What you would notice also when reading the documentation of both tasks, is that the names of their properties are really confusing and do not describe their functionalities. Take for example the targetPath property, that actually defines the “Path to the folder or file you want to publish.”, i.e. the source ! Who would use the word target to describe the source from where you publish things, I mean seriously ! Especially when you haven’t mentioned anywhere in the article the actual destination. Would it be so difficult to use the naming : source and destination ?
This can be really irritating for someone who is new to Azure DevOps or to this field in general, and believe me if you are, Azure DevOps documentation is loaded with hideousness like this.
Directories
$(Pipeline.Workspace)
This is the main directory of a pipeline, it contains the folder of the repository as well as all the folders of the build pipeline. It is the default destination directory of the Download Pipeline Artifacts and the default source (targetPath) of the Publish Pipeline Artifacts task.
$(System.ArtifactsDirectory)
alias : $(System.DefaultWorkingDirectory), $(Agent.ReleaseDirectory)
This directory is used during release pipeline or release stage to receive downloaded artifacts from build pipeline or from previous stages. It is the default destination directory of the Download Build Artifacts task.
$(Build.ArtifactStagingDirectory)
alias : $(Build.StagingDirectory)
This is the directory that is used to hold the artifacts (that are basically generated from build, publish … tasks) and that are intended to be transferred to destinations such as the pipeline, next stages of a pipeline.
This location holds artifacts and files from the output of tasks such as build or publish or by directly copying them to it using the CopyFiles, to be used later as a source for deploying these files or pushing them to there next stage, as shown in the following figure:
$(Agent.RootDirectory)
This is the root directory of the agent where all folders will be created.
This is the parent folder of for example : $(Pipeline.Workspace).
$(Pipeline.Workspace) = $(Agent.RootDirectory)\1
Example : “C:\agent\_work”
Container
This directory represents the current Pipeline, it is the default directory a task like Publish Pipeline Artifacts task puts the artifacts to be used by the next stage.
