steps.checkout definition

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

steps:
- checkout: string # Required as first property. Configures checkout for the specified repository.
  clean: true | false # If true, run git clean -ffdx followed by git reset --hard HEAD before fetching.
  fetchDepth: string # Depth of Git graph to fetch.
  fetchFilter: string # Filter Git history.
  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).
  workspaceRepo: true | false # When true, use the repository root directory as the default working directory for the pipeline. The default is false.
  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.

Definitions that reference this definition: steps

Properties

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.

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.

fetchFilter string.
Use fetchFilter to filter Git history for partial cloning. The fetchFilter setting supports treeless and blobless fetches. For a treeless fetch, specify fetchFilter: tree:0 and to specify a blobless fetch, specify fetchFilter: blob:none. The default is no filtering.

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). By default this folder must be under the agent working directory structure. To set a path outside of the agent working directory, set a pipeline variable named AZP_AGENT_ALLOW_WORK_DIRECTORY_REPOSITORIES to true, and use the prefix ../ at the start of your checkout path. Supported on agent version 3.230.0 and higher.

workspaceRepo string.
When true, use the repository root directory as the default working directory for the pipeline. The default is false.

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 target.
Environment in which to run this task.

enabled boolean.
Run this task when the job runs?

env string dictionary.
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.

Note

Pipelines may be configured with a job level timeout. If the job level timeout interval elapses before your step completes, the running job (including your step) is terminated, even if the step is configured with a longer timeoutInMinutes interval. For more information, see Timeouts.

retryCountOnTaskFailure string.
Number of retries if the task fails.

Remarks

• Shallow fetch
• Clean property
• Sync tags

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.

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.

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

• Supported source repositories