Fazer check-out de vários repositórios em seu pipeline

Artigo
06/16/2023

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

Os pipelines geralmente dependem de vários repositórios que contêm código-fonte, ferramentas, scripts ou outros itens necessários para compilar seu código. Usando várias etapas checkout em seu pipeline, você pode buscar e fazer check-out de outros repositórios além daquele que você usa para armazenar seu pipeline YAML.

Especificar vários repositórios

Os repositórios podem ser especificados como um recurso de repositório ou em linha com a etapa checkout.

Há suporte para os tipos de repositório a seguir.

Git do Azure Repos (git)

Azure DevOps Server (limitado a repositórios na mesma organização)
Azure DevOps Services

GitHub (github)

Azure DevOps Services

GitHubEnterprise (githubenterprise)

Azure DevOps Services

Nuvem do Bitbucket (bitbucket)

Azure DevOps Services

Importante

Somente os repositórios Git do Azure Repos (git) na mesma organização que o pipeline têm suporte para check-out de vários repositórios no Azure DevOps Server.

Observação

O Azure Pipelines fornece configurações para Limitar o escopo de trabalho para repositórios Git do Azure Repos. Para fazer check-out de repositórios Git do Azure Repos hospedados em outro projeto, Limitar o escopo de trabalho deve ser configurado para permitir o acesso. Para obter mais informações, confira Limitar o escopo da autorização do trabalho.

Há suporte para as combinações de etapas checkout a seguir.

Nenhuma etapa checkout

O comportamento padrão é como se checkout: self fosse a primeira etapa e o check-out foi feito no repositório atual.

Uma etapa checkout: none única

Nenhum repositório foi sincronizado ou o check-out foi feito.

Uma etapa checkout: self única

O check-out foi feito no repositório atual.

Uma única etapa checkout que não é self ou none

O check-out é feito no repositório designado em vez de self.

Várias etapas checkout

O check-out é feito em cada repositório designado para uma pasta com o nome do repositório, a menos que um path diferente seja especificado na etapa checkout. Para marcar self como um dos repositórios, use checkout: self como uma das etapas checkout.

Observação

Ao fazer check-out de repositórios Git do Azure Repos diferentes daquele que contém o pipeline, você pode ser solicitado a autorizar o acesso a esse recurso antes que o pipeline seja executado pela primeira vez. Para obter mais informações, consulte Por que sou solicitado a autorizar recursos na primeira vez que tento fazer check-out de um repositório diferente? na seção de perguntas frequentes.

Definição de recurso do repositório

Você deve usar um recurso de repositório se o tipo de repositório exigir uma conexão de serviço ou outro campo de recursos estendidos. Os seguintes tipos de repositório exigem uma conexão de serviço.

Tipo do repositório	Conexão de serviço
Nuvem do Bitbucket	Nuvem do Bitbucket
GitHub	GitHub
GitHub Enterprise Server	GitHub Enterprise Server
Repositórios Git do Azure Repos em uma organização diferente do pipeline	Azure Repos/Team Foundation Server

Você pode usar um recurso de repositório mesmo que seu tipo de repositório não exija uma conexão de serviço, por exemplo, se você tiver um recurso de repositório definido para modelos em um repositório diferente.

No exemplo a seguir, três repositórios são declarados como recursos do repositório. O repositório Git do Azure Repos em outra organização, o GitHub e os recursos do repositório Bitbucket Cloud exigem conexões de serviço, que são especificadas como endpoint para esses recursos de repositório. Este exemplo tem quatro etapas checkout, que verifica os três repositórios declarados como recursos de repositório junto com o repositório self atual que contém o YAML do pipeline.

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)

Se o repositório self for chamado de CurrentRepo, o comando script produzirá a seguinte saída: CurrentRepo MyAzureReposGitRepo MyBitbucketRepo MyGitHubRepo. Neste exemplo, os nomes dos repositórios (conforme especificado pela propriedade name no recurso de repositório) são usados para as pastas porque nenhum path é especificado na etapa de verificação. Para obter mais informações sobre os nomes e locais das pastas do repositório, confira a seção Caminho do check-out a seguir.

Check-out de sintaxe embutida

Se o repositório não exigir uma conexão de serviço, você poderá declará-lo embutido com a etapa checkout.

Observação

Somente os repositórios Git do Azure Repos na mesma organização podem usar a sintaxe embutida. Repositórios Git do Azure Repos em uma organização diferente e outros tipos de repositório com suporte exigem uma conexão de serviço e devem ser declarados como um recurso de repositório.

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

Observação

No exemplo anterior, o repositório de check-out self é especificado para fazer check-out da origem do repositório associado ao pipeline.

Se você estiver usando o repositório Git padrão do Azure Repos (que tem o mesmo nome do projeto), use o formato - checkout: git://MyRepo/MyRepo.

Caminho do check-out

A menos que um path seja especificado na etapa checkout, o código-fonte é colocado em um diretório padrão. Esse diretório é diferente dependendo se você está fazendo check-out de um ou vários repositórios.

Repositório único: se você tiver uma única etapa checkout em seu trabalho ou não tiver nenhuma etapa de check-out equivalente a checkout: self, o check-out será feito no código-fonte em um diretório chamado s localizado como uma subpasta de (Agent.BuildDirectory). Se (Agent.BuildDirectory) for C:\agent\_work\1, o check-out será feito no código para C:\agent\_work\1\s.
Vários repositórios: se você tiver várias etapas checkout em seu trabalho, o check-out será feito no código-fonte em diretórios nomeados com base nos repositórios como uma subpasta do s em (Agent.BuildDirectory). Se (Agent.BuildDirectory) for C:\agent\_work\1 e seus repositórios forem nomeados tools e code, o check-out será feito no código em C:\agent\_work\1\s\tools e C:\agent\_work\1\s\code.

Observação

Se nenhum path for especificado na etapa checkout, o nome do repositório será usado para a pasta, não o valor repository usado para fazer referência ao repositório na etapa checkout.

Se um path for especificado para uma etapa checkout, esse caminho será usado em relação a (Agent.BuildDirectory).

Observação

Se você estiver usando caminhos padrão, a adição de uma segunda etapa checkout de repositório alterará o caminho padrão do código para o primeiro repositório. Por exemplo, o check-out de um código de um repositório chamado tools será feito em C:\agent\_work\1\s quando tools for o único repositório, mas se um segundo repositório for adicionado, o check-out de tools será feito em C:\agent\_work\1\s\tools. Se você tiver alguma etapa que dependa do código-fonte estar no local original, essas etapas deverão ser atualizadas.

Como fazer check-out de uma referência específica

O branch padrão é verificado, a menos que você escolha uma ref. específica.

Se você estiver usando a sintaxe embutida, designe a referência acrescentando @<ref>. Por exemplo:

- 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.

Ao usar um recurso de repositório, especifique a referência usando a propriedade ref. O exemplo a seguir faz check-out do branch features/tools/ do repositório designado.

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

steps:
- checkout: MyGitHubRepo

O exemplo a seguir usa marcas para fazer check-out do commit referenciado por MyTag.

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

steps:
- checkout: MyGitHubRepo

Gatilhos

Você pode disparar um pipeline quando uma atualização é enviada por push para o repositório self ou para qualquer repositório declarado como recurso. Isso é útil, por exemplo, nos seguintes cenários:

Você consome uma ferramenta ou uma biblioteca de um repositório diferente. Você deseja executar testes para seu aplicativo sempre que a ferramenta ou biblioteca for atualizada.
Você mantém o arquivo YAML em um repositório separado do código do aplicativo. Você deseja disparar o pipeline sempre que uma atualização é enviada por push para o repositório de aplicativos.

Importante

Os gatilhos de recursos do repositório só funcionam para repositórios Git do Azure Repos na mesma organização e quando o tipo de repositório self é o Azure Repos Git. Eles não funcionam para recursos do repositório GitHub ou Bitbucket.

batch não é compatível com gatilhos de recursos do repositório.

Se você não especificar uma seção trigger em um recurso de repositório, o pipeline não será disparado por alterações nesse repositório. Se você especificar uma seção trigger, o comportamento para disparar será semelhante a como os gatilhos de CI funcionam para o repositório self.

Se você especificar uma seção trigger para vários recursos do repositório, uma alteração em qualquer um deles iniciará uma nova execução.

Quando um pipeline é disparado, o Azure Pipelines precisa determinar a versão do arquivo YAML que deve ser usado e uma versão para cada repositório que deve ser verificada. Se uma alteração no repositório self disparar um pipeline, a confirmação que disparou o pipeline será usada para determinar a versão do arquivo YAML. Se uma alteração em qualquer outro recurso de repositório disparar o pipeline, a versão mais recente do YAML do branch padrão do repositório self será usada.

Quando uma atualização em um dos repositórios dispara um pipeline, as seguintes variáveis são definidas com base no gatilho do repositório:

Build.Repository.ID
Build.Repository.Name
Build.Repository.Provider
Build.Repository.Uri
Build.SourceBranch
Build.SourceBranchName
Build.SourceVersion
Build.SourceVersionMessage

Para o repositório de gatilho, a confirmação que disparou o pipeline determina a versão do código que está com check-out. Para outros repositórios, o ref definido no YAML para esse recurso de repositório determina a versão padrão que está com check-out.

Considere o exemplo a seguir, em que o repositório self contém o arquivo YAML e os repositórios A e B contêm código-fonte adicional.

trigger:
- main
- feature

resources:
  repositories:
  - repository: A
    type: git
    name: MyProject/A
    ref: main
    trigger:
    - main

  - repository: B
    type: git
    name: MyProject/B
    ref: release
    trigger:
    - main
    - release
steps:
- checkout: self
- checkout: A
- checkout: B

A tabela a seguir mostra quais versões são submetidas a check-out para cada repositório por um pipeline usando o arquivo YAML acima.

Alteração feita em	Pipeline disparado	Versão do YAML	Versão do `self`	Versão do `A`	Versão do `B`
`main` em `self`	Sim	commit de `main` que disparou o pipeline	commit de `main` que disparou o pipeline	mais recente de `main`	mais recente de `release`
`feature` em `self`	Sim	commit de `feature` que disparou o pipeline	commit de `feature` que disparou o pipeline	mais recente de `main`	mais recente de `release`
`main` em `A`	Sim	mais recente de `main`	mais recente de `main`	commit de `main` que disparou o pipeline	mais recente de `release`
`main` em `B`	Sim	mais recente de `main`	mais recente de `main`	mais recente de `main`	commit de `main` que disparou o pipeline
`release` em `B`	Sim	mais recente de `main`	mais recente de `main`	mais recente de `main`	commit de `release` que disparou o pipeline

Você também pode disparar o pipeline ao criar ou atualizar uma solicitação de pull em qualquer um dos repositórios. Para fazer isso, declare os recursos do repositório nos arquivos YAML como nos exemplos acima e configure uma política de branch no repositório (somente Azure Repos).

Detalhes do repositório

Quando você fizer check-out em vários repositórios, alguns detalhes sobre o repositório self ficam disponíveis como variáveis. Quando você usa gatilhos de vários repositórios, algumas dessas variáveis têm informações sobre o repositório de gatilho. Detalhes sobre todos os repositórios consumidos pelo trabalho estão disponíveis como um objeto de contexto de modelo chamado resources.repositories.

Por exemplo, para obter a referência de um repositório não self, você pode gravar um pipeline como este:

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"

Perguntas frequentes

Por que não consigo fazer check-out de um repositório de outro projeto? Costumava funcionar.
Por que sou solicitado a autorizar recursos na primeira vez que tento fazer check-out de um repositório diferente?

Por que não consigo fazer check-out de um repositório de outro projeto? Costumava funcionar.

O Azure Pipelines fornece a opção Limitar escopo da autorização do trabalho para a configuração atual do projeto, que, quando habilitado, não permite que o pipeline acesse recursos fora do projeto que contém o pipeline. Essa configuração pode ser definida no nível da organização ou do projeto. Se essa configuração estiver habilitada, você não poderá fazer check-out de um repositório em outro projeto, a menos que conceda acesso explicitamente. Para obter mais informações, confira Escopo da autorização do trabalho.

Por que sou solicitado a autorizar recursos na primeira vez que tento fazer check-out de um repositório diferente?

Ao fazer check-out de repositórios Git do Azure Repos diferentes daquele que contém o pipeline, você pode ser solicitado a autorizar o acesso a esse recurso antes que o pipeline seja executado pela primeira vez. Esses prompts são exibidos na página de resumo da execução do pipeline.

This pipeline needs permission to access a resource