title	description	ms.date	monikerRange
steps.checkout definition	Configure how the pipeline checks out source code.	03/02/2023	>=azure-pipelines-2019

steps.checkout definition

:::moniker range=">=azure-pipelines-2019"

Use checkout to configure how the pipeline checks out source code.

:::moniker-end

:::moniker range="=azure-pipelines"

steps:
- checkout: string # Required as first property. Configures checkout for the specified repository.
  clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  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: 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: string | target # Environment in which to run this task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
  retryCountOnTaskFailure: string # Number of retries if the task fails.

:::moniker-end

:::moniker range="=azure-pipelines-2022"

steps:
- checkout: string # Required as first property. Configures checkout for the specified repository.
  clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  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: 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: string | target # Environment in which to run this task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.
  retryCountOnTaskFailure: string # Number of retries if the task fails.

:::moniker-end

:::moniker range=">=azure-pipelines-2020 <=azure-pipelines-2020.1"

steps:
- checkout: string # Required as first property. Configures checkout for the specified repository.
  clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  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: 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: string | target # Environment in which to run this task.
  enabled: boolean # Run this task when the job runs?
  env: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.

:::moniker-end

:::moniker range="=azure-pipelines-2019.1"

steps:
- checkout: string # Required as first property. Whether or not to check out the repository containing this pipeline definition.
  clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  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: 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: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.

:::moniker-end

:::moniker range="=azure-pipelines-2019"

steps:
- checkout: string # Required as first property. Whether or not to check out the repository containing this pipeline definition.
  clean: string # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  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: 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: # Variables to map into the process's environment.
    string: string # Name/value pairs
  name: string # ID of the step.
  timeoutInMinutes: string # Time to wait for this task to complete before the server kills it.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

Definitions that that reference this definition: steps

:::moniker-end

Properties

:::moniker range=">=azure-pipelines-2020"

checkout string. Required as first property.
Configures checkout for the specified repository. Specify self, none, repository name, or repository resource. For more information, see Check out multiple repositories in your pipeline.

Note

If no checkout step is present, it defaults to self for jobs.job.step.checkout and none for jobs.deployment.steps.checkout.

:::moniker-end

:::moniker range=">=azure-pipelines-2019 <=azure-pipelines-2019.1"

checkout string. Required as first property.
Whether or not to check out the repository containing this pipeline definition. Specify self or none.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

clean string.
If true, run git clean -ffdx followed by git reset --hard HEAD before fetching. true | false.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

fetchDepth string.
Depth of Git graph to fetch.

:::moniker-end

:::moniker range="=azure-pipelines"

fetchTags string.
Set to 'true' to sync tags when fetching the repo, or 'false' to not sync tags. See remarks for the default behavior.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

lfs string.
Set to 'true' to download Git-LFS files. Default is not to download them.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

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.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

submodules string.
Set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules. Default is not to fetch submodules.

:::moniker-end

:::moniker range=">=azure-pipelines-2019.1"

path string.
Where to put the repository. The root directory is $(Pipeline.Workspace).

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

condition string.
Evaluate this condition expression to determine whether to run this task.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

continueOnError boolean.
Continue running even on failure?

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

displayName string.
Human-readable name for the task.

:::moniker-end

:::moniker range=">=azure-pipelines-2020"

target target.
Environment in which to run this task.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

enabled boolean.
Run this task when the job runs?

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

env string dictionary.
Variables to map into the process's environment.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

name string.
ID of the step. Acceptable values: [-_A-Za-z0-9]*.

:::moniker-end

:::moniker range=">=azure-pipelines-2019"

timeoutInMinutes string.
Time to wait for this task to complete before the server kills it.

:::moniker-end

:::moniker range=">=azure-pipelines-2022"

retryCountOnTaskFailure string.
Number of retries if the task fails.

:::moniker-end

Remarks

:::moniker range="azure-pipelines"

Shallow fetch
Clean property
Sync tags

:::moniker-end

:::moniker range="<azure-pipelines"

Shallow fetch
Clean property

:::moniker-end

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: 0 in your checkout step.

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

If the clean property is unset, then its default value is configured by the clean setting in the UI settings for YAML pipelines, which is set to true 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.

::: moniker range="= azure-pipelines"

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.

Important

A Sync tags setting of true in the UI takes precedence over a fetchTags: false statement in the YAML. If Sync tags is set to true in the UI, tags are synced even if fetchTags is set to false in the YAML.

::: moniker-end

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

::: moniker range=">= azure-pipelines-2020"

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.

::: moniker-end

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

steps-checkout.md

steps-checkout.md

steps.checkout definition

Properties

Remarks

Shallow fetch

Clean property

Sync tags

Default behavior

Examples

See also

Files

steps-checkout.md

Latest commit

History

steps-checkout.md

File metadata and controls

steps.checkout definition

Properties

Remarks

Shallow fetch

Clean property

Sync tags

Default behavior

Examples

See also