steps.checkout definition
Use checkout to configure how the pipeline checks out source code.
steps:
- checkout: string # Required as first property. Whether or not to check out the repository containing this pipeline definition. (self, none)
clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. (true, false)
fetchDepth: string # Depth of Git graph to fetch.
lfs: string # set to 'true' to download Git-LFS files. Default is not to download them.
persistCredentials: string # set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
submodules: true | recursive # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
condition: string # Evaluate this condition expression to determine whether to run this task.
continueOnError: boolean # Continue running even on failure?. (false,n,no,off,on,true,y,yes)
displayName: string # Human-readable name for the task.
enabled: boolean # Run this task when the job runs?. (false,n,no,off,on,true,y,yes)
env: # Variables to map into the process's environment
string: string # Name/value pairs.
name: string # ID of the step. ([-_A-Za-z0-9]*)
timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
Properties that use this definition: steps
Properties
checkout
string
Required as first parameter. Whether or not to check out the repository containing this pipeline definition. Acceptable values: self, noneclean
string
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. Acceptable values: true, falsefetchDepth
string
Depth of Git graph to fetch.lfs
string
Set to 'true' to download Git-LFS files. Default is not to download them.persistCredentials
string
Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.submodules
string
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.condition
string
Evaluate this condition expression to determine whether to run this task.continueOnError
boolean
Continue running even on failure?displayName
string
Human-readable name for the task.enabled
boolean
Run this task when the job runs?env
string name/value pairs
Variables to map into the process's environment.name
string
ID of the step. Acceptable values: [_A-Za-z0-9]*timeoutInMinutes
string
Time to wait for this task to complete before the server kills it.steps:
- checkout: string # Required as first property. Whether or not to check out the repository containing this pipeline definition. (self, none)
clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. (true, false)
fetchDepth: string # Depth of Git graph to fetch.
lfs: string # set to 'true' to download Git-LFS files. Default is not to download them.
persistCredentials: string # set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
submodules: true | recursive # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
path: string # Where to put the repository. The root directory is $(Pipeline.Workspace).
condition: string # Evaluate this condition expression to determine whether to run this task.
continueOnError: boolean # Continue running even on failure?. (false,n,no,off,on,true,y,yes)
displayName: string # Human-readable name for the task.
enabled: boolean # Run this task when the job runs?. (false,n,no,off,on,true,y,yes)
env: # Variables to map into the process's environment
string: string # Name/value pairs.
name: string # ID of the step. ([-_A-Za-z0-9]*)
timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
Properties that use this definition: steps
Properties
checkout
string
Required as first parameter. Whether or not to check out the repository containing this pipeline definition. Acceptable values: self, noneclean
string
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. Acceptable values: true, falsefetchDepth
string
Depth of Git graph to fetch.lfs
string
Set to 'true' to download Git-LFS files. Default is not to download them.persistCredentials
string
Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.submodules
string
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.path
string
Where to put the repository. The root directory is $(Pipeline.Workspace).condition
string
Evaluate this condition expression to determine whether to run this task.continueOnError
boolean
Continue running even on failure?displayName
string
Human-readable name for the task.enabled
boolean
Run this task when the job runs?env
string name/value pairs
Variables to map into the process's environment.name
string
ID of the step. Acceptable values: [_A-Za-z0-9]*timeoutInMinutes
string
Time to wait for this task to complete before the server kills it.steps:
- checkout: string # Required as first property. Alias of the repository resource to check out or 'none'.
clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. (true, false)
fetchDepth: string # Depth of Git graph to fetch.
lfs: string # set to 'true' to download Git-LFS files. Default is not to download them.
persistCredentials: string # set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
submodules: true | recursive # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
path: string # Where to put the repository. The root directory is $(Pipeline.Workspace).
condition: string # Evaluate this condition expression to determine whether to run this task.
continueOnError: boolean # Continue running even on failure?. (false,n,no,off,on,true,y,yes)
displayName: string # Human-readable name for the task.
target: stepTarget # Environment in which to run this task
enabled: boolean # Run this task when the job runs?. (false,n,no,off,on,true,y,yes)
env: # Variables to map into the process's environment
string: string # Name/value pairs.
name: string # ID of the step. ([-_A-Za-z0-9]*)
timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
Properties that use this definition: steps
Properties
checkout
string
Required as first parameter. Alias of the repository resource to check out or 'none'.clean
string
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. Acceptable values: true, falsefetchDepth
string
Depth of Git graph to fetch.lfs
string
Set to 'true' to download Git-LFS files. Default is not to download them.persistCredentials
string
Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.submodules
string
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.path
string
Where to put the repository. The root directory is $(Pipeline.Workspace).condition
string
Evaluate this condition expression to determine whether to run this task.continueOnError
boolean
Continue running even on failure?displayName
string
Human-readable name for the task.target
enabled
boolean
Run this task when the job runs?env
string name/value pairs
Variables to map into the process's environment.name
string
ID of the step. Acceptable values: [_A-Za-z0-9]*timeoutInMinutes
string
Time to wait for this task to complete before the server kills it.steps:
- checkout: string # Required as first property. Alias of the repository resource to check out or 'none'.
clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. (true, false)
fetchDepth: string # Depth of Git graph to fetch.
lfs: string # set to 'true' to download Git-LFS files. Default is not to download them.
persistCredentials: string # set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
submodules: true | recursive # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
path: string # Where to put the repository. The root directory is $(Pipeline.Workspace).
condition: string # Evaluate this condition expression to determine whether to run this task.
continueOnError: boolean # Continue running even on failure?. (false,n,no,off,on,true,y,yes)
displayName: string # Human-readable name for the task.
target: stepTarget # Environment in which to run this task
enabled: boolean # Run this task when the job runs?. (false,n,no,off,on,true,y,yes)
env: # Variables to map into the process's environment
string: string # Name/value pairs.
name: string # ID of the step. ([-_A-Za-z0-9]*)
timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
Properties that use this definition: steps
Properties
checkout
string
Required as first parameter. Alias of the repository resource to check out or 'none'.clean
string
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. Acceptable values: true, falsefetchDepth
string
Depth of Git graph to fetch.lfs
string
Set to 'true' to download Git-LFS files. Default is not to download them.persistCredentials
string
Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.submodules
string
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.path
string
Where to put the repository. The root directory is $(Pipeline.Workspace).condition
string
Evaluate this condition expression to determine whether to run this task.continueOnError
boolean
Continue running even on failure?displayName
string
Human-readable name for the task.target
enabled
boolean
Run this task when the job runs?env
string name/value pairs
Variables to map into the process's environment.name
string
ID of the step. Acceptable values: [_A-Za-z0-9]*timeoutInMinutes
string
Time to wait for this task to complete before the server kills it.steps:
- checkout: string # Required as first property. Alias of the repository resource to check out or 'none'.
clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. (true, false)
fetchDepth: string # Depth of Git graph to fetch.
lfs: string # set to 'true' to download Git-LFS files. Default is not to download them.
persistCredentials: string # set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
submodules: true | recursive # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
path: string # Where to put the repository. The root directory is $(Pipeline.Workspace).
condition: string # Evaluate this condition expression to determine whether to run this task.
continueOnError: boolean # Continue running even on failure?. (false,n,no,off,on,true,y,yes)
displayName: string # Human-readable name for the task.
target: stepTarget # Environment in which to run this task
enabled: boolean # Run this task when the job runs?. (false,n,no,off,on,true,y,yes)
env: # Variables to map into the process's environment
string: string # Name/value pairs.
name: string # ID of the step. ([-_A-Za-z0-9]*)
timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
retryCountOnTaskFailure: string # Number of retries if the task fails.
Properties that use this definition: steps
Properties
checkout
string
Required as first parameter. Alias of the repository resource to check out or 'none'.clean
string
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. Acceptable values: true, falsefetchDepth
string
Depth of Git graph to fetch.lfs
string
Set to 'true' to download Git-LFS files. Default is not to download them.persistCredentials
string
Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.submodules
string
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.path
string
Where to put the repository. The root directory is $(Pipeline.Workspace).condition
string
Evaluate this condition expression to determine whether to run this task.continueOnError
boolean
Continue running even on failure?displayName
string
Human-readable name for the task.target
enabled
boolean
Run this task when the job runs?env
string name/value pairs
Variables to map into the process's environment.name
string
ID of the step. Acceptable values: [-_A-Za-z0-9]*timeoutInMinutes
string
Time to wait for this task to complete before the server kills it.retryCountOnTaskFailure
string
Number of retries if the task fails.steps:
- checkout: string # Required as first property. Alias of the repository resource to check out or 'none'.
clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. (true, false)
fetchDepth: string # Depth of Git graph to fetch.
fetchTags: string # Set to 'true' to sync tags when fetching the repo, or 'false' to not sync tags. See remarks for the default behavior..
lfs: string # set to 'true' to download Git-LFS files. Default is not to download them.
persistCredentials: string # set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.
submodules: true | recursive # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.
path: string # Where to put the repository. The root directory is $(Pipeline.Workspace).
condition: string # Evaluate this condition expression to determine whether to run this task.
continueOnError: boolean # Continue running even on failure?. (false,n,no,off,on,true,y,yes)
displayName: string # Human-readable name for the task.
target: stepTarget # Environment in which to run this task
enabled: boolean # Run this task when the job runs?. (false,n,no,off,on,true,y,yes)
env: # Variables to map into the process's environment
string: string # Name/value pairs.
name: string # ID of the step. ([-_A-Za-z0-9]*)
timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
retryCountOnTaskFailure: string # Number of retries if the task fails.
Properties that use this definition: steps
Properties
checkout
string
Required as first parameter. Alias of the repository resource to check out or 'none'.clean
string
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. Acceptable values: true, falsefetchDepth
string
Depth of Git graph to fetch.fetchTags
string
Set to 'true' to sync tags when fetching the repo, or 'false' to not sync tags. See remarks for the default behavior.lfs
string
Set to 'true' to download Git-LFS files. Default is not to download them.persistCredentials
string
Set to 'true' to leave the OAuth token in the Git config after the initial fetch. The default is not to leave it.submodules
string
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.path
string
Where to put the repository. The root directory is $(Pipeline.Workspace).condition
string
Evaluate this condition expression to determine whether to run this task.continueOnError
boolean
Continue running even on failure?displayName
string
Human-readable name for the task.target
enabled
boolean
Run this task when the job runs?env
string name/value pairs
Variables to map into the process's environment.name
string
ID of the step. Acceptable values: [-_A-Za-z0-9]*timeoutInMinutes
string
Time to wait for this task to complete before the server kills it.retryCountOnTaskFailure
string
Number of retries if the task fails.Remarks
Shallow fetch
Important
New pipelines created after the September 2022 Azure DevOps sprint 209 update have Shallow fetch enabled by default and configured with a depth of 1. Previously the default was not to shallow fetch. To check your pipeline, view the Shallow fetch setting in the pipeline settings UI.
To disable shallow fetch, you can perform one of the following two options.
- Disable the Shallow fetch option in the pipeline settings UI.
- Explicitly set
fetchDepth: 0in yourcheckoutstep.
To configure the fetch depth for a pipeline, you can either set the fetchDepth property in the checkout step, or configure the Shallow fetch setting in the pipeline settings UI.
Note
If you explicitly set fetchDepth in your checkout step, that setting takes priority over the setting configured in the pipeline settings UI. Setting fetchDepth: 0 fetches all history and overrides the Shallow fetch setting.
Clean property
The default value if the clean property is unset is configured by the clean setting in the UI settings for YAML pipelines, which is set to false by default. In addition to the cleaning option available using checkout, you can also configure cleaning in a workspace. For more information about workspaces and clean options, see the workspace topic in Jobs.
Sync tags
The checkout step uses the --tags option when fetching the contents of a Git repository. This causes the server to fetch all tags as well as all objects that are pointed to by those tags. This increases the time to run the task in a pipeline, particularly if you have a large repository with a number of tags. Furthermore, the checkout step syncs tags even when you enable the shallow fetch option, thereby possibly defeating its purpose. To reduce the amount of data fetched or pulled from a Git repository, Microsoft has added a new option to checkout to control the behavior of syncing tags. This option is available both in classic and YAML pipelines.
Whether to synchronize tags when checking out a repository can be configured in YAML by setting the fetchTags property, and in the UI by configuring the Sync tags setting.
To configure the setting in YAML, set the fetchTags property.
steps:
- checkout: self
fetchTags: true
To configure the setting in the pipeline UI, edit your YAML pipeline, and choose More actions, Triggers, YAML, Get sources, and check or uncheck the Sync tags checkbox. For more information, see Sync tags.
Default behavior
- For existing pipelines created before the release of Azure DevOps sprint 209, released in September 2022, the default for syncing tags remains the same as the existing behavior before the Sync tags options was added, which is
true. - For new pipelines created after Azure DevOps sprint release 209, the default for syncing tags is
false.
Examples
To avoid syncing sources at all:
steps:
- checkout: none
Note
If you're running the agent in the Local Service account and want to modify the current repository by using git operations or loading git submodules, give the proper permissions to the Project Collection Build Service Accounts user.
- checkout: self
submodules: true
persistCredentials: true
To check out multiple repositories in your pipeline, use multiple checkout steps:
- checkout: self
- checkout: git://MyProject/MyRepo
- checkout: MyGitHubRepo # Repo declared in a repository resource
For more information, see Check out multiple repositories in your pipeline.
See also
Feedback
Submit and view feedback for