Opções de pipeline para repositórios Git

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Ao editar um pipeline que usa um Repositório do Git, em um projeto do Azure DevOps, GitHub, GitHub Enterprise Server, Bitbucket Cloud ou outro Repositório do Git, você tem as opções a seguir.

Recurso	Azure Pipelines	Azure DevOps Server 2019 e posterior	TFS 2018
Branch	Sim	Sim	Sim
Clean	Sim	Sim	Sim
Fontes de marca ou rótulo	Projeto; Somente clássico	Projeto da equipe	Projeto da equipe
Relatar status de build	Sim	Sim	Sim
Fazer check-out de submódulos	Sim	Sim	Sim
Fazer check-out de arquivos no LFS	Sim	Sim	Sim
Clonar um segundo repositório	Sim	Sim	Sim
Não sincronizar fontes	Sim	Sim	Sim
Fetch superficial	Sim	Sim	Sim

Observação

Clique em Configurações avançadas na tarefa Obter Fontes para ver algumas das opções acima.

Branch

Esse é o branch que você deseja que seja o padrão ao enfileirar esse build manualmente. Se você definir um gatilho agendado para o build, esse será o branch do qual o build obterá as fontes mais recentes. O branch padrão não tem influência quando o build é disparado pela CI (integração contínua). Normalmente, você o definirá como o branch padrão do repositório (por exemplo, "mestre").

Limpar o repositório local no agente

Você pode executar diferentes formas de limpeza do diretório de trabalho do agente auto-hospedado antes que um build seja executado.

Em geral, para obter um desempenho mais rápido de seus agentes auto-hospedados, não limpe o repositório. Nesse caso, para obter o melhor desempenho, verifique se você também está compilando incrementalmente, desabilitando qualquer opção Limpar da tarefa ou ferramenta que você está usando para compilar.

Se você precisar limpar o repositório (por exemplo, para evitar problemas causados por arquivos residuais de uma compilação anterior), suas opções para isso são descritas abaixo.

Observação

A limpeza não será eficaz se você estiver usando um agente hospedado pela Microsoft, pois você receberá um novo agente todas as vezes. Ao usar agentes auto-hospedados, dependendo de como seus pools de agentes estão configurados, você pode obter um novo agente para execuções de pipeline subsequentes (ou fases ou trabalhos no mesmo pipeline). Portanto, não limpar não é uma garantia de que execuções, trabalhos ou fases subsequentes poderão acessar saídas de execuções, trabalhos ou fases anteriores.

YAML

Azure Pipelines, Azure DevOps Server 2019 e mais recente

Há várias opções de limpeza diferentes disponíveis para pipelines YAML.

• A etapa checkout tem uma opção clean. Quando definido como true, o pipeline executa o execute git clean -ffdx && git reset --hard HEAD, antes de buscar o repositório. Para obter mais informações, confira Check-out.
• A configuração workspace de job tem várias opções de limpeza (saídas, recursos, tudo). Para obter mais informações, confira Workspace.
• A interface do usuário de configurações de pipeline tem uma configuração Limpar, que quando definida como true é equivalente a especificar clean: true para cada etapa checkout no seu pipeline. Para definir a configuração Limpar:

  1. Edite seu pipeline, escolha ... e selecione Gatilhos.

     

  2. Selecione YAML, Obter fontes e defina a configuração Limpar desejada. O padrão é true.

     

Para substituir as configurações de limpeza ao executar um pipeline manualmente, você pode usar os parâmetros de runtime. No exemplo a seguir, um parâmetro de runtime é usado para definir a configuração de limpeza de check-out.

parameters:
- name: clean
  displayName: Checkout clean
  type: boolean
  default: true
  values:
  - false
  - true

trigger:
- main

pool: FabrikamPool
#  vmImage: 'ubuntu-latest'

steps:
- checkout: self
  clean: ${{ parameters.clean }}

Por padrão, clean é definido como true, mas pode ser substituído ao executar manualmente o pipeline, desmarcando a caixa de seleção Limpeza de check-out, que é adicionada para o parâmetro de runtime.

Clássico

Azure Pipelines, TFS 2018, TFS 2017.2, TFS 2017.3

Selecione uma das seguintes opções:

• Fontes: o pipeline de build desfaz eventuais alterações em $(Build.SourcesDirectory). Mais especificamente, os comandos Git a seguir são executados antes de efetuar fetch da fonte.

  git clean -ffdx
  git reset --hard HEAD
  

• Diretório de fontes e saída: a mesma operação que a opção Fontes acima e que, além disso, exclui e recria $(Build.BinariesDirectory). Observe que o $(Build.ArtifactStagingDirectory) e $(Common.TestResultsDirectory) são sempre excluídos e recriados antes de cada build, independentemente de qualquer uma dessas configurações.

• Diretório de fontes: exclui e recria $(Build.SourcesDirectory). Isso resulta na inicialização de um novo Repositório do Git local para cada build.

• Todos os diretórios de build: exclui e recria $(Agent.BuildDirectory). Isso resulta na inicialização de um novo Repositório do Git local para cada build.

Fontes de rótulo

Talvez você queira rotular seus arquivos de código-fonte para permitir que sua equipe identifique facilmente qual versão de cada arquivo está incluída no build concluído. Você também tem a opção de especificar se o código-fonte deve ser rotulado para todos os builds ou apenas para builds bem-sucedidos.

Observação

Você só pode usar esse recurso quando o repositório de origem no seu build for um Repositório do GitHub ou um Repositório do Git ou TFVC do seu projeto.

Em Formato de rótulo, você pode usar variáveis definidas pelo usuário e predefinidas que têm um escopo de "Todos". Por exemplo:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)

As quatro primeiras variáveis são predefinidas. My.Variable pode ser definido por você na guia variáveis.

O pipeline de build rotula suas fontes com uma Tag do git.

Algumas variáveis de build podem produzir um valor que não é um rótulo válido. Por exemplo, variáveis como $(Build.RequestedFor) e $(Build.DefinitionName) podem conter um espaço em branco. Se o valor contiver um espaço em branco, a marca não será criada.

Depois que as fontes são marcadas pelo pipeline de build, um artefato do Git com a referência refs/tags/{tag} é adicionado automaticamente ao build concluído. Isso oferece à sua equipe rastreabilidade adicional e uma maneira mais amigável de navegar do build para o código que foi compilado. A tag é considerada um artefato de build, pois é produzida pelo build. Quando o build é excluído manualmente ou por meio de uma política de retenção, a marca também é excluída.

Relatar status de build (Azure Pipelines, TFS 2018 e mais recente)

Você tem a opção de dar à sua equipe uma exibição do status de build do repositório de origem remoto.

Se suas fontes estiverem em um Repositório do Git do Azure Repos no seu projeto, essa opção exibirá um selo na página Código para indicar aprovação ou falha do build. O status de build é exibido nas seguintes guias:

• Arquivos: indica o status do build mais recente para o branch selecionado.
• Commits: indica o status de build de cada commit (isso requer que o gatilho de CI (integração contínua) esteja habilitado para os builds).
• Branches: indica o status do build mais recente para cada branch.

Se você usar vários pipelines de build para o mesmo repositório no seu projeto, poderá habilitar essa opção para um ou mais pipelines. No caso de essa opção estar habilitada em vários pipelines, o selo na página Código indicará o status do build mais recente em todos os pipelines. Os membros da equipe podem clicar no selo de status de build para exibir o status de build mais recente para cada um dos pipelines de build.

GitHub

Se suas fontes estiverem no GitHub, essa opção publicará o status do seu build no GitHub usando as Verificações do GitHub ou APIs de Status. Se o build for disparado de uma solicitação de pull do GitHub, você poderá exibir o status na página de solicitações de pull do GitHub. Isso também permite que você defina políticas de status no GitHub e automatize mesclagens. Se o build for disparado pela CI (integração contínua), você poderá exibir o status de build no commit ou branch no GitHub.

Outros tipos de repositórios remotos Git

Se a origem estiver em qualquer outro tipo de repositório remoto, você não poderá usar o Azure Pipelines ou o TFS para publicar automaticamente o status de build nesse repositório. No entanto, você pode usar um selo de build como uma maneira de integrar e mostrar status de build nas suas experiências de controle de versão.

Caminho de check-out

Se você estiver fazendo check-out de apenas um repositório, por padrão, o check-out do código-fonte será realizado em um diretório chamado s. Para pipelines YAML, você pode alterar isso especificando checkout com um path. O caminho especificado é relativo a $(Agent.BuildDirectory). Por exemplo: se o valor do caminho de check-out for mycustompath e $(Agent.BuildDirectory) for C:\agent\_work\1, o código-fonte será verificado em C:\agent\_work\1\mycustompath.

Se você estiver usando várias etapas checkout, fazendo check-out de vários repositórios e não especificando explicitamente a pasta usando path, cada repositório será colocado em uma subpasta de s com o nome do repositório. Por exemplo, se você marcar dois repositórios chamados tools e code, o check-out do código-fonte será realizado em C:\agent\_work\1\s\tools e C:\agent\_work\1\s\code.

Observe que o valor do caminho de check-out não pode ser definido para subir nenhum nível de diretório acima de $(Agent.BuildDirectory), portanto, path\..\anotherpath resultará em um caminho de check-out válido (ou seja, C:\agent\_work\1\anotherpath), mas o mesmo não ocorrerá para um valor como ..\invalidpath (ou seja, C:\agent\_work\invalidpath).

Se você estiver usando várias etapas checkout e verificando vários repositórios e quiser especificar explicitamente a pasta usando path, evite definir o caminho que é a subpasta do caminho de outra etapa de check-out (ou seja, C:\agent\_work\1\s\repo1 e C:\agent\_work\1\s\repo1\repo2). Caso contrário, a subpasta da etapa de check-out será desmarcada pela limpeza de outro repositório. Observe que esse caso é válido se a opção de limpeza for true para repo1)

Observação

O caminho de check-out só pode ser especificado para pipelines YAML. Para obter mais informações, confira Check-out no Esquema YAML.

Fazer check-out de submódulos

Selecione se deseja baixar arquivos dos submódulos. Você pode obter os submódulos imediatos ou todos os submódulos aninhados para qualquer profundidade de recursão. Se você quiser usar LFS com submódulos, confira a observação sobre como usar LFS com submódulos.

Observação

Para obter mais informações sobre a sintaxe YAML para verificar submódulos, confira Check-out no esquema YAML.

O pipeline de build fará check-out de seus submódulos do Git, desde que eles sejam de um dos seguintes tipos:

• Não autenticado: um repositório público não autenticado sem necessidade de credenciais para clonar ou efetuar fetch.

• Autenticado:

  • Contido na mesma conta do projeto, da organização do GitHub ou do Bitbucket Cloud que o Repositório do Git especificado acima.

  • Adicionado usando uma URL relativa ao repositório main. Por exemplo, este seria verificado: git submodule add /../../submodule.git mymodule Este não seria verificado: git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule

Submódulos autenticados

Observação

Verifique se você registrou seus submódulos usando HTTPS e não usando SSH.

As mesmas credenciais usadas pelo agente para obter as fontes do repositório main também são usadas para obter as fontes de submódulos.

Se o repositório main e os submódulos estiverem em um Repositório do Git do Azure Repos no projeto do Azure DevOps, você poderá selecionar a conta usada para acessar as fontes. Na guia Opções, no menu Criar escopo de autorização de trabalho, selecione:

• Coleção de projetos para usar a conta de serviço de Build de Coleção de Projetos

• Projeto atual para usar a conta do Serviço de Build do Projeto.

Verifique se qualquer conta usada tem acesso ao repositório main, bem como aos submódulos.

Se o repositório main e os submódulos estiverem na mesma organização do GitHub, o token armazenado na conexão de serviço do GitHub será usado para acessar as fontes.

Alternativa ao uso da opção Fazer check-out de submódulos

Em alguns casos, você não pode usar a opção Fazer check-out de submódulos. Você pode ter um cenário em que um conjunto diferente de credenciais é necessário para acessar os submódulos. Isso pode acontecer, por exemplo, se o repositório main e os repositórios do submódulo não estiverem armazenados na mesma organização do Azure DevOps ou serviço Git.

Se você não puder usar a opção Fazer checkout de submódulos, poderá usar uma etapa de script personalizada para efetuar fetch de submódulos. Obtenha um PAT (token de acesso pessoal) e prefixe-o com pat:. Depois, codifique essa cadeia de caracteres prefixada em base64 para criar um token de autenticação básico. Por fim, adicione este script ao pipeline:

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: basic <BASE64_ENCODED_TOKEN_DESCRIBED_ABOVE>" submodule update --init --recursive

Substitua "<BASIC_AUTH_TOKEN>" pelo token codificado em Base64.

Use uma variável secreta em seu projeto ou pipeline de build para armazenar o token de autenticação básico gerado. Use essa variável para preencher o segredo no comando Git acima.

Observação

P: Por que não posso usar um gerenciador de credenciais do Git no agente? R: Armazenar as credenciais de submódulo em um gerenciador de credenciais do Git instalado em seu agente de build privado geralmente não é eficaz, pois o gerenciador de credenciais poderá solicitar que você insira novamente as credenciais sempre que o submódulo for atualizado. Isso não é desejável durante builds automatizados, quando a interação do usuário não é possível.

Fazer check-out de arquivos no LFS

Selecione se deseja baixar os arquivos do LFS (armazenamento de arquivos grandes).

No editor clássico, marque a caixa de seleção para habilitar essa opção.

Em um build YAML, adicione uma etapa de check-out com lfs definido como true:

steps:
- checkout: self
  lfs: true

Se você estiver usando o TFS ou se estiver usando o Azure Pipelines com um agente auto-hospedado, instale git-lfs no agente para que essa opção funcione. Se os agentes hospedados usarem o Windows, use a variável System.PreferGitFromPath para garantir que os pipelines usem as versões do git e do git-lfs instaladas no computador. Para obter mais informações, confira Qual versão do Git meu agente executa?

Como usar o Git LFS com submódulos

Se um submódulo contiver arquivos do LFS, o Git LFS deverá ser configurado antes de fazer check-out dos submódulos. Os agentes macOS e Linux hospedados pela Microsoft vêm pré-configurados dessa maneira. Os agentes do Windows e agentes macOS/Linux auto-hospedados podem não vir.

Como solução alternativa, se você estiver usando YAML, poderá adicionar a seguinte etapa antes do seu checkout:

steps:
- script: |
    git config --global --add filter.lfs.required true
    git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f"
    git config --global --add filter.lfs.process "git-lfs filter-process"
    git config --global --add filter.lfs.clean "git-lfs clean -- %%f"
  displayName: Configure LFS for use with submodules
- checkout: self
  lfs: true
  submodules: true
# ... rest of steps ...

Clonar um segundo repositório

Por padrão, o pipeline está associado a um repositório do Azure Repos ou um provedor externo. Esse é o repositório que pode disparar builds em commits e solicitações de pull.

Talvez você queira incluir fontes de um segundo repositório no seu pipeline. Você pode fazer isso gravando um script.

git clone https://github.com/Microsoft/TypeScript.git

Se o repositório não for público, você precisará passar a autenticação para o comando Git.

Azure Repos

Você pode clonar vários repositórios no mesmo projeto que o pipeline usando o check-out de vários repositórios.

Se você precisar clonar um repositório de outro projeto que não seja público, precisará se autenticar como um usuário com acesso a esse projeto.

Observação

Use uma variável de segredo para armazenar credenciais com segurança.

As variáveis de segredo não são disponibilizadas automaticamente para scripts como variáveis de ambiente. Confira Variáveis de segredo para saber como mapeá-las.

No Azure Repos, você pode usar um token de acesso pessoal com a permissão Código (Leitura). Envie isso como o campo de senha em um cabeçalho de autorização "Básico", sem um nome de usuário. (Em outras palavras, codificar em base64 o valor de :<PAT>, incluindo os dois-pontos.)

AUTH=$(echo -n ":$REPO_PAT" | openssl base64 | tr -d '\n')
git -c http.<repo URL>.extraheader="AUTHORIZATION: basic $AUTH" clone <repo URL> --no-checkout --branch master

Não sincronizar fontes

Trabalhos de não implantação buscam fontes automaticamente. Use essa opção se quiser ignorar esse comportamento. Essa opção pode ser útil em casos em que você deseja:

• Usar git init, config e fetch usando suas opções personalizadas.

• Usar um pipeline de build para executar apenas a automação (por exemplo, alguns scripts) que não dependem do código no controle de versão.

Se você quiser desabilitar o download de fontes:

• Azure Pipelines, TFS 2018 e mais recente: clique em Configurações avançadas e selecione Não sincronizar fontes.

Observação

Quando você usa essa opção, o agente também ignora a execução de comandos Git que limpam o repositório.

Fetch superficial

Selecione se deseja limitar até que ponto o histórico deve ser baixado. Efetivamente, isso resulta em git fetch --depth=n. Se o repositório for grande, essa opção poderá tornar o pipeline de build mais eficiente. Seu repositório poderá ser grande se estiver em uso por um longo tempo e tiver um histórico considerável. Também poderá ser grande se você tiver adicionado e excluído arquivos grandes posteriormente.

Nesses casos, essa opção pode ajudar você a conservar recursos de rede e armazenamento. Ela também pode economizar tempo. O motivo pelo qual ela nem sempre economiza tempo é porque, em algumas situações, o servidor pode precisar gastar tempo calculando os commits a serem baixados para obter a profundidade especificada.

Observação

Quando o build é enfileirado, o branch a ser compilado é resolvido para um ID do commit. Em seguida, o agente busca o branch e faz check-out do commit desejado. Há uma pequena janela entre quando um branch é resolvido para uma ID do commit e quando o agente executa o check-out. Se o branch for atualizado rapidamente e você definir um valor muito pequeno para fetch superficial, o commit poderá não existir quando o agente tentar fazer check-out dele. Se isso acontecer, aumente a configuração de profundidade de busca superficial.

Depois de marcar a caixa de seleção para habilitar essa opção, na caixa Profundidade, especifique o número de commits.

Dica

A variável Agent.Source.Git.ShallowFetchDepth mencionada abaixo também funciona e substitui os controles da caixa de seleção. Dessa forma, você pode modificar a configuração ao enfileirar o build.

Preferir o Git no caminho

Por padrão, o agente do Windows usa a versão do Git que é agrupada com o software do agente. A Microsoft recomenda usar a versão do Git que é agrupada com o agente, mas você tem várias opções para substituir esse comportamento padrão e usar a versão do Git que o computador do agente instalou no caminho.

• Defina uma variável de pipeline chamada System.PreferGitFromPath como true nos seus pipelines.
• Nos agentes auto-hospedados, você pode criar um arquivo chamado .env no diretório raiz do agente e adicionar uma linha System.PreferGitFromPath=true ao arquivo. Para obter mais informações, confira Como definir variáveis de ambiente diferentes para cada agente individual?

Para ver a versão do Git usada por um pipeline, você pode examinar os logs para obter uma etapa checkout no seu pipeline, conforme mostrado no exemplo a seguir.

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

Essa configuração é sempre verdadeira em agentes que não são do Windows.

Opções de gatilho para outro Git

Quando um Repositório do Git externo/outro é especificado, os builds de CI exigem que o repositório esteja acessível pela Internet. Se o repositório estiver usando um firewall ou proxy, somente os builds agendados e manuais funcionarão.

Perguntas frequentes

Quais protocolos o agente de build pode usar com o Git?

O agente dá suporte a HTTPS.

O agente ainda não dá suporte a SSH. Confira Permitir que o build use a autenticação SSH ao conferir submódulos do Git.