Check out multiple repositories in your pipeline

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Pipelines often rely on multiple repositories that contain source, tools, scripts, or other items that you need to build your code. By using multiple checkout steps in your pipeline, you can fetch and check out other repositories in addition to the one you use to store your YAML pipeline.

Specify multiple repositories

Repositories can be specified as a repository resource, or inline with the checkout step.

The following repository types are supported.

The following combinations of checkout steps are supported.

Repository resource definition

You must use a repository resource if your repository type requires a service connection or other extended resources field. The following repository types require a service connection.

You may use a repository resource even if your repository type doesn't require a service connection, for example if you have a repository resource defined already for templates in a different repository.

In the following example, three repositories are declared as repository resources. The Azure Repos Git repository in another organization, GitHub, and Bitbucket Cloud repository resources require service connections, which are specified as the endpoint for those repository resources. This example has four checkout steps, which checks out the three repositories declared as repository resources along with the current self repository that contains the pipeline YAML.

resources:
  repositories:
  - repository: MyGitHubRepo # The name used to reference this repository in the checkout step
    type: github
    endpoint: MyGitHubServiceConnection
    name: MyGitHubOrgOrUser/MyGitHubRepo
  - repository: MyBitbucketRepo
    type: bitbucket
    endpoint: MyBitbucketServiceConnection
    name: MyBitbucketOrgOrUser/MyBitbucketRepo
  - repository: MyAzureReposGitRepository # In a different organization
    endpoint: MyAzureReposGitServiceConnection
    type: git
    name: OtherProject/MyAzureReposGitRepo

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- checkout: self
- checkout: MyGitHubRepo
- checkout: MyBitbucketRepo
- checkout: MyAzureReposGitRepository

- script: dir $(Build.SourcesDirectory)

If the self repository is named CurrentRepo, the script command produces the following output: CurrentRepo MyAzureReposGitRepo MyBitbucketRepo MyGitHubRepo. In this example, the names of the repositories (as specified by the name property in the repository resource) are used for the folders, because no path is specified in the checkout step. For more information on repository folder names and locations, see the following Checkout path section.

Inline syntax checkout

If your repository doesn't require a service connection, you can declare it inline with your checkout step.

steps:
- checkout: self
- checkout: git://MyProject/MyRepo # Azure Repos Git repository in the same organization

Checkout path

Unless a path is specified in the checkout step, source code is placed in a default directory. This directory is different depending on whether you are checking out a single repository or multiple repositories.

• Single repository: If you have a single checkout step in your job, or you have no checkout step which is equivalent to checkout: self, your source code is checked out into a directory called s located as a subfolder of (Agent.BuildDirectory). If (Agent.BuildDirectory) is C:\agent\_work\1, your code is checked out to C:\agent\_work\1\s.

• Multiple repositories: If you have multiple checkout steps in your job, your source code is checked out into directories named after the repositories as a subfolder of s in (Agent.BuildDirectory). If (Agent.BuildDirectory) is C:\agent\_work\1 and your repositories are named tools and code, your code is checked out to C:\agent\_work\1\s\tools and C:\agent\_work\1\s\code.

  Note

  If no path is specified in the checkout step, the name of the repository is used for the folder, not the repository value which is used to reference the repository in the checkout step.

If a path is specified for a checkout step, that path is used, relative to (Agent.BuildDirectory).

Workspace repository

When multiple checkout steps (and different paths for each) are used in your pipeline, you may want to use the root directory of one the repositories as the default working directory. If so, you can set the workspaceRepo input to true for the related checkout step.

- checkout: git://project/first
  path: repo/first-repo

- checkout: git://project/second
  path: repo/second-repo
  workspaceRepo: true

- pwsh: pwd
# Expected output: $(Pipeline.Workspace)/repo/second-repo

Checking out a specific ref

The default branch is checked out unless you designate a specific ref.

If you are using inline syntax, designate the ref by appending @<ref>. For example:

- checkout: git://MyProject/MyRepo@features/tools # checks out the features/tools branch
- checkout: git://MyProject/MyRepo@refs/heads/features/tools # also checks out the features/tools branch
- checkout: git://MyProject/MyRepo@refs/tags/MyTag # checks out the commit referenced by MyTag.

When using a repository resource, specify the ref using the ref property. The following example checks out the features/tools/ branch of the designated repository.

resources:
  repositories:
  - repository: MyGitHubRepo
    type: github
    endpoint: MyGitHubServiceConnection
    name: MyGitHubOrgOrUser/MyGitHubRepo
    ref: features/tools

steps:
- checkout: MyGitHubRepo

The following example uses tags to check out the commit referenced by MyTag.

resources:
  repositories:
  - repository: MyGitHubRepo
    type: github
    endpoint: MyGitHubServiceConnection
    name: MyGitHubOrgOrUser/MyGitHubRepo
    ref: refs/tags/MyTag

steps:
- checkout: MyGitHubRepo

Repository details

When you check out multiple repositories, some details about the self repository are available as variables. When you use multi-repo triggers, some of those variables have information about the triggering repository instead. Details about all of the repositories consumed by the job are available as a template context object called resources.repositories.

For example, to get the ref of a non-self repository, you could write a pipeline like this:

resources:
  repositories:
  - repository: other
    type: git
    name: MyProject/OtherTools

variables:
  tools.ref: $[ resources.repositories['other'].ref ]

steps:
- checkout: self
- checkout: other
- bash: |
    echo "Tools version: $TOOLS_REF"

FAQ

• Why can't I check out a repository from another project? It used to work.
• Why am I prompted to authorize resources the first time I try to check out a different repository?

Why can't I check out a repository from another project? It used to work.

Azure Pipelines provides a Limit job authorization scope to current project setting, that when enabled, doesn't permit the pipeline to access resources outside of the project that contains the pipeline. This setting can be set at either the organization or project level. If this setting is enabled, you won't be able to check out a repository in another project unless you explicitly grant access. For more information, see Job authorization scope.

Why am I prompted to authorize resources the first time I try to check out a different repository?

When you check out Azure Repos Git repositories other than the one containing the pipeline, you may be prompted to authorize access to that resource before the pipeline runs for the first time. These prompts are displayed on the pipeline run summary page.

Choose View or Authorize resources, and follow the prompts to authorize the resources.

For more information, see Troubleshooting authorization for a YAML pipeline.