Opções de pipeline para repositórios Git

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

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

Caraterística Pipelines do Azure Azure DevOps Server 2019 e superior TFS 2018
Filial Sim Sim Sim
Limpar Sim Sim Sim
Fontes de tags ou rótulos Projeto; Apenas clássico Projeto de equipa Projeto de equipa
Status da compilação do relatório Sim Sim Sim
Confira os submódulos Sim Sim Sim
Confira arquivos do LFS Sim Sim Sim
Clone um segundo repo Sim Sim Sim
Não sincronizar fontes Sim Sim Sim
Busca rasa Sim Sim Sim

Nota

Clique em Configurações avançadas na tarefa Obter códigos-fonte para ver algumas das opções acima.

Filial

Esta é a ramificação que você deseja que seja o padrão quando você enfileirar manualmente esta compilação. Se você definir um gatilho agendado para a compilação, esta é a ramificação da qual sua compilação obterá as fontes mais recentes. A ramificação padrão não tem influência quando a compilação é acionada por meio de integração contínua (CI). Normalmente, você definirá isso como o mesmo que a ramificação padrão do repositório (por exemplo, "master").

Limpe o repositório local no agente

Você pode executar diferentes formas de limpeza do diretório de trabalho do seu agente auto-hospedado antes que uma compilação seja executada.

Em geral, para um desempenho mais rápido de seus agentes auto-hospedados, não limpe o repositório. Neste caso, para obter o melhor desempenho, certifique-se de que também está a criar de forma incremental, desativando qualquer opção Limpar da tarefa ou ferramenta que está a utilizar 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 estão abaixo.

Nota

A limpeza não é eficaz se você estiver usando um agente hospedado pela Microsoft, porque você receberá um novo agente toda vez. 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 estágios ou trabalhos no mesmo pipeline), portanto , não limpar não é uma garantia de que execuções, trabalhos ou estágios subsequentes poderão acessar saídas de execuções, trabalhos ou estágios anteriores.

Nota

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 estágios ou trabalhos no mesmo pipeline), portanto , não limpar não é uma garantia de que execuções, trabalhos ou estágios subsequentes poderão acessar saídas de execuções, trabalhos ou estágios anteriores. Você pode usar artefatos de compilação para compartilhar saídas de uma execução, estágio ou trabalho de pipeline com execuções, estágios ou trabalhos subsequentes.

Azure Pipelines, Azure DevOps Server 2019 e versões mais recentes

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

  • O checkout passo tem uma clean opção. Quando definido como true, o pipeline é executado execute git clean -ffdx && git reset --hard HEAD antes de buscar o repo. Para obter mais informações, consulte Checkout.
  • A workspace configuração para job tem várias opções limpas (saídas, recursos, tudo). Para obter mais informações, consulte Espaço de trabalho.
  • A interface do usuário de configurações do pipeline tem uma configuração Limpa , que quando definida como true é equivalente a especificar clean: true para cada checkout etapa do pipeline. Para definir a configuração Limpar :

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

      Editar gatilhos.

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

      Configuração limpa.

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

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 Checkout clean que é adicionada para o parâmetro runtime.

Fontes de etiquetas

Você pode querer rotular seus arquivos de código-fonte para permitir que sua equipe identifique facilmente qual versão de cada arquivo está incluída na compilação concluída. Você também tem a opção de especificar se o código-fonte deve ser rotulado para todas as compilações ou apenas para compilações bem-sucedidas.

Nota

Você só pode usar esse recurso quando o repositório de origem em sua compilação for um repositório GitHub ou um repositório Git ou TFVC do seu projeto.

No formato Label, 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.Variablepode ser definido por si no separador variáveis.

O pipeline de construção rotula seus códigos-fonte com uma tag Git.

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

Depois que os códigos-fonte são marcados pelo pipeline de compilação, um artefato com a ref refs/tags/{tag} do Git é adicionado automaticamente à compilação concluída. Isso dá à sua equipe rastreabilidade adicional e uma maneira mais amigável de navegar da compilação para o código que foi criado. A tag é considerada um artefato de construção, uma vez que é produzida pela compilação. Quando a compilação é excluída manualmente ou por meio de uma política de retenção, a tag também é excluída.

Status da compilação do relatório (Azure Pipelines, TFS 2018 e mais recente)

Você tem a opção de dar à sua equipe uma visão do status da compilação a partir do repositório de origem remoto.

Se suas fontes estiverem em um repositório Git do Azure Repos em seu projeto, essa opção exibirá um selo na página Código para indicar se a compilação está passando ou falhando. O status da compilação é exibido nas seguintes guias:

  • Arquivos: indica o status da compilação mais recente para a ramificação selecionada.
  • Commits: indica o status de compilação de cada commit (isso requer que o gatilho de integração contínua (CI) seja habilitado para suas compilações).
  • Ramos: Indica o status da compilação mais recente para cada ramificação.

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

GitHub

Se suas fontes estiverem no GitHub, essa opção publicará o status de sua compilação no GitHub usando Verificações do GitHub ou APIs de status. Se sua compilação for acionada a partir de uma solicitação pull do GitHub, você poderá visualizar o status na página pull requests do GitHub. Isso também permite que você defina políticas de status no GitHub e automatize mesclagens. Se sua compilação for acionada por integração contínua (CI), você poderá visualizar o status da compilação na confirmação ou ramificação no GitHub.

Outros tipos de repositórios remotos Git

Se sua 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 da compilação nesse repositório. No entanto, você pode usar um selo de compilação como uma maneira de integrar e mostrar o status da compilação em suas experiências de controle de versão.

Caminho de check-out

Se você estiver fazendo check-out de um único repositório, por padrão, o check-out do código-fonte será feito em um diretório chamado s. Para pipelines YAML, você pode alterar isso especificando checkout com um patharquivo . 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 fará check-out no C:\agent\_work\1\mycustompath.

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

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

Se você estiver usando várias checkout etapas e fazendo check-out de vários repositórios, e quiser especificar explicitamente a pasta usando path, considere evitar definir caminho que é subpasta do caminho de outra etapa de checkout (ou seja C:\agent\_work\1\s\repo1 , e C:\agent\_work\1\s\repo1\repo2), caso contrário, a subpasta da etapa de checkout será limpa pela limpeza de outro repositório. Por favor, note que este caso é válido se a opção limpa for verdadeira para repo1)

Nota

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

Dar saída dos submódulos

Selecione se deseja baixar arquivos de submódulos. Você pode optar por obter os submódulos imediatos ou todos os submódulos aninhados em qualquer profundidade de recursão. Se você quiser usar o LFS com submódulos, certifique-se de ver a nota sobre o uso do LFS com submódulos.

Nota

Para obter mais informações sobre a sintaxe YAML para fazer check-out de submódulos, consulte Check-out no esquema YAML.

O pipeline de construção verificará seus submódulos do Git desde que sejam:

  • Não autenticado: um repositório público não autenticado sem credenciais necessárias para clonar ou buscar.

  • Autenticado:

    • Contido no mesmo projeto, organização do GitHub ou conta do Bitbucket Cloud como o repositório Git especificado acima.

    • Adicionado usando uma URL relativa ao repositório principal. 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

Nota

Certifique-se de ter registrado seus submódulos usando HTTPS e não usando SSH.

As mesmas credenciais que são usadas pelo agente para obter os códigos-fonte do repositório principal também são usadas para obter os códigos-fonte para submódulos.

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

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

  • Projeto atual para usar a conta do Project Build Service.

Certifique-se de que qualquer conta que você use tenha acesso tanto ao repositório principal quanto aos submódulos.

Se o repositório principal 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 de submódulos Checkout

Em alguns casos, não é possível usar a opção Checkout 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 principal e os repositórios do submódulo não estiverem armazenados na mesma organização do Azure DevOps ou no mesmo serviço Git.

Se você não puder usar a opção Checkout submódulos , poderá usar uma etapa de script personalizada para buscar submódulos. Primeiro, obtenha um token de acesso pessoal (PAT) e prefixe-o com pat:. Em seguida, base64-encode essa cadeia de caracteres prefixada para criar um token de autenticação básico. Finalmente, adicione este script ao seu pipeline:

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

Certifique-se de substituir "<BASIC_AUTH_TOKEN>" pelo seu token codificado em Base64.

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

Nota

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

Confira arquivos do LFS

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

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

Em uma compilação YAML, adicione uma etapa de checkout 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, deverá instalar git-lfs no agente para que essa opção funcione. Se seus agentes hospedados usam o Windows, considere usar a System.PreferGitFromPath variável para garantir que os pipelines usem as versões do git e do git-lfs instaladas na máquina. Para obter mais informações, consulte Qual versão do Git meu agente executa?

Usando o Git LFS com submódulos

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

Como solução alternativa, se você estiver usando YAML, você pode adicionar a seguinte etapa antes do :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 ...

Clone um segundo repo

Por padrão, seu pipeline está associado a um repositório do Azure Repos ou a um provedor externo. Este é o repositório que pode acionar compilações em confirmações e solicitações pull.

Você pode incluir fontes de um segundo repositório em seu pipeline. Você pode fazer isso escrevendo 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.

Repositórios do Azure

Seu pipeline já terá acesso a outros repositórios em seu projeto, e você pode cloná-los em seu pipeline usando um comando script, conforme mostrado no exemplo a seguir.

- script: | 
    git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" https://organization@dev.azure.com/project/FabrikamFiber/_git/reponame

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

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

Nota

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

As variáveis secretas não são disponibilizadas automaticamente para scripts como variáveis de ambiente. Consulte Variáveis secretas sobre como mapeá-las.

Para os repositórios do Azure, você pode usar um token de acesso pessoal com a permissão Código (Leitura). Envie como o campo de senha em um cabeçalho de autorização "Básico" sem um nome de usuário. (Em outras palavras, base64-codificar 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

Os trabalhos que não são de implantação buscam fontes automaticamente. Use essa opção se quiser ignorar esse comportamento. Esta opção pode ser útil nos casos em que pretende:

  • Git init, config e fetch usando suas próprias opções personalizadas.

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

Se você quiser desativar o download de fontes:

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

Nota

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

Busca rasa

Selecione se você deseja limitar a distância no histórico para download. Efetivamente, isso resulta em git fetch --depth=n. Se o repositório for grande, essa opção pode tornar o pipeline de compilação mais eficiente. Seu repositório pode ser grande se estiver em uso por um longo tempo e tiver um histórico considerável. Também pode ser grande se você adicionou e depois excluiu arquivos grandes.

Nesses casos, essa opção pode ajudá-lo a conservar recursos de rede e armazenamento. Também pode poupar tempo. A razão pela qual nem sempre economiza tempo é porque, em algumas situações, o servidor pode precisar gastar tempo calculando as confirmações a serem baixadas para a profundidade que você especificar.

Nota

Quando a compilação é enfileirada, a ramificação a ser compilada é resolvida para uma ID de confirmação. Em seguida, o agente busca a ramificação e verifica a confirmação desejada. Há uma pequena janela entre quando uma ramificação é resolvida para uma ID de confirmação e quando o agente executa o check-out. Se a ramificação for atualizada rapidamente e você definir um valor muito pequeno para busca superficial, a confirmação pode não existir quando o agente tentar fazer check-out. Se isso acontecer, aumente a configuração de profundidade de busca rasa.

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

Gorjeta

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

Prefira o Git do caminho

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

Para ver a versão do Git usada por um pipeline, você pode examinar os logs para uma checkout etapa 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 Git Outro/externo é especificado, as compilações de CI exigem que o repositório esteja acessível a partir da Internet. Se o repositório estiver atrás de um firewall ou proxy, apenas compilações agendadas e manuais funcionarão.

FAQ

Quais protocolos o agente de compilação pode usar com o Git?

O agente suporta HTTPS.

O agente ainda não suporta SSH. Consulte Permitir que a compilação use a autenticação SSH ao fazer check-out dos submódulos do Git.

Eu uso o TFS local e não vejo alguns desses recursos. Porque não?

Alguns desses recursos estão disponíveis apenas no Azure Pipelines e ainda não estão disponíveis localmente. Alguns recursos estão disponíveis no local se você tiver atualizado para a versão mais recente do TFS.