Compartilhar via

Criar repositórios Git do TFS ou Git do Azure Repos

  • Artigo

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

O Azure Pipelines pode criar e validar automaticamente cada solicitação de pull e confirmar o repositório do Git do Azure Repos.

Escolher um repositório para criar

Você cria um pipeline selecionando primeiro um repositório e, em seguida, um arquivo YAML nesse repositório. O repositório no qual o arquivo YAML está presente é chamado de repositório self. Por padrão, esse é o repositório que o pipeline compila.

Posteriormente, você pode configurar o pipeline para marcar um repositório diferente ou vários repositórios. Para saber como fazer isso, confira check-out de vários repositórios.

O Azure Pipelines deve ter acesso aos repositórios para disparar seus builds e efetuar fetch do código durante os builds. Normalmente, um pipeline tem acesso a repositórios no mesmo projeto. Mas, se você quiser acessar repositórios em um projeto diferente, precisará atualizar as permissões concedidas aos tokens de acesso ao trabalho.

Gatilhos de CI

Os gatilhos de CI (integração contínua) fazem com que um pipeline seja executado sempre que você envia uma atualização por push para os branches especificados ou envia tags especificadas por push.

Os pipelines YAML são configurados por padrão com um gatilho de CI em todas as ramificações, a menos que a configuração de gatilho Desabilitar CI YAML implícito, introduzida no Azure DevOps sprint 227, esteja habilitada. A configuração de gatilho Desabilitar CI YAML implícito pode ser definida no nível da organização ou no nível do projeto. Quando a configuração Desabilitar gatilho de CI YAML implícito está habilitada, os gatilhos de CI para pipelines YAML não são habilitados se o pipeline YAML não tem uma seção trigger. Por padrão, Desabilitar gatilho YAML CI implícito não está habilitado.

Branches

Você pode controlar quais branches obtêm gatilhos de CI com uma sintaxe simples:

trigger:
- main
- releases/*

Você pode especificar o nome completo do branch (por exemplo, main) ou um curinga (por exemplo, releases/*). Confira Curingas para obter informações sobre a sintaxe curinga.

Observação

Você não pode usar variáveis em gatilhos, pois as variáveis são avaliadas em runtime (depois que o gatilho é acionado).

Observação

Se você usar modelos para criar arquivos YAML, só poderá especificar gatilhos no arquivo YAML principal para o pipeline. Você não poderá especificar gatilhos nos arquivos de modelo.

Para gatilhos mais complexos que usam exclude ou batch, você precisa usar a sintaxe completa, conforme mostrado no exemplo a seguir.

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

No exemplo acima, o pipeline será disparado se uma alteração for enviada por push para main ou para qualquer branch de versões. No entanto, ele não será disparado se uma alteração for feita em um branch de versões que começa com old.

Se você especificar uma cláusula exclude sem uma cláusula include, isso será equivalente a especificar * na cláusula include.

Além de especificar nomes de ramificação nas listas branches, você também pode configurar gatilhos com base em tags usando o seguinte formato:

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

Se você não especificou nenhum gatilho e a configuração de gatilho Desabilitar YAML CI implícito não está habilitada, o padrão é como se você escrevesse:

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

Importante

Quando você especifica um gatilho, ele substitui o gatilho implícito padrão, e apenas pushes para branches configurados explicitamente para serem incluídos dispararão um pipeline. As inclusões são processadas primeiro e, em seguida, as exclusões são removidas dessa lista.

Execuções de CI de envio em lote

Se você tiver muitos membros da equipe carregando alterações com frequência, talvez queira reduzir o número de execuções iniciadas. Se você definir batch como true, quando um pipeline estiver em execução, o sistema aguardará até que a execução seja concluída e iniciará outra execução com todas as alterações que ainda não foram criadas.

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

Observação

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

Para esclarecer este exemplo, digamos que um push A para main causou a execução do pipeline acima. Enquanto esse pipeline está em execução, os pushes adicionais B e C ocorrem no repositório. Essas atualizações não iniciam novas execuções independentes imediatamente. Mas depois que a primeira execução é concluída, todos os pushes até esse ponto de tempo são agrupados em lote e uma nova execução é iniciada.

Observação

Se o pipeline tiver vários trabalhos e fases, a primeira execução ainda deverá atingir um estado terminal concluindo ou ignorando todos os trabalhos e fases dela antes que a segunda execução possa ser iniciada. Por esse motivo, você precisa ter cuidado ao usar esse recurso em um pipeline com várias fases ou aprovações. Se você quiser colocar em lote seus builds nesses casos, é recomendável dividir o processo de CI/CD em dois pipelines : um para build (com envio em lote) e outro para implantações.

Caminhos

Você pode especificar caminhos de arquivo a serem incluídos ou excluídos.

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

Se estiver usando o Azure DevOps Server 2019.1 ou inferior, ao especificar caminhos, você precisará especificar explicitamente branches nos quais disparar. Você não pode disparar um pipeline apenas com um filtro de caminho; você também precisa ter um filtro de branch e os arquivos alterados que correspondem ao filtro de caminho precisam ser de um branch que corresponda ao filtro de branch. Se você estiver usando o Azure DevOps Server 2020 ou mais recente, poderá omitir branches para filtrar em todos os branches em conjunto com o filtro de caminho.

Os curingas são compatíveis com filtros de caminho. Por exemplo, você pode incluir todos os caminhos que correspondem a src/app/**/myapp*. Você pode usar caracteres curinga (**, * ou ?) ao especificar filtros de caminho.

  • Os caminhos são sempre especificados em relação à raiz do repositório.
  • Se você não definir filtros de caminho, a pasta raiz do repositório será incluída implicitamente por padrão.
  • Se você excluir um caminho, também não poderá incluí-lo, a menos que o qualifique para uma pasta mais profunda. Por exemplo, se você excluir /tools, poderá incluir /tools/trigger-runs-on-these
  • A ordem dos filtros de caminho não importa.
  • Os caminhos no Git diferenciam maiúsculas de minúsculas. Use a mesma formatação de maiúsculas e minúsculas que as pastas reais.
  • Você não pode usar variáveis em caminhos, pois as variáveis são avaliadas em runtime (depois que o gatilho é acionado).

Marcas

Além de especificar tags nas listas branches, conforme abordado na seção anterior, você pode especificar tags diretamente para incluir ou excluir:

# specific tag
trigger:
  tags:
    include:
    - v2.*
    exclude:
    - v2.0

Se você não especificar nenhum gatilho de tag, por padrão, as tags não dispararão pipelines.

Importante

Se você especificar tags em combinação com filtros de branch, o gatilho será acionado se o filtro de branch for atendido ou o filtro de tag for atendido. Por exemplo, se uma tag enviada por push atender ao filtro de branch, o pipeline será disparado mesmo se a tag for excluída pelo filtro de tag, porque o push atendeu ao filtro de branch.

Recusar a CI

Desabilitar o gatilho de CI

Você pode recusar totalmente os gatilhos de CI especificando trigger: none.

# A pipeline with no CI trigger
trigger: none

Importante

Quando você envia uma alteração por push para um branch, o arquivo YAML nesse branch é avaliado para determinar se uma execução de CI deve ser iniciada.

Ignorando a CI para pushes individuais

Você também pode dizer ao Azure Pipelines para ignorar a execução de um pipeline que um push normalmente dispararia. Basta incluir ***NO_CI*** na mensagem de qualquer um dos commits que fazem parte de um push e o Azure Pipelines ignorará a execução de CI para esse push.

Você também pode dizer ao Azure Pipelines para ignorar a execução de um pipeline que um push normalmente dispararia. Basta incluir [skip ci] na mensagem ou descrição de qualquer um dos commits que fazem parte de um push e o Azure Pipelines ignorará a execução de CI para esse push. Você também pode usar qualquer uma das variações a seguir.

  • [skip ci] ou [ci skip]
  • skip-checks: true ou skip-checks:true
  • [skip azurepipelines] ou [azurepipelines skip]
  • [skip azpipelines] ou [azpipelines skip]
  • [skip azp] ou [azp skip]
  • ***NO_CI***

Usando o tipo de gatilho em condições

Executar diferentes etapas, trabalhos ou estágios no pipeline, dependendo do tipo de gatilho que iniciou a execução, é um cenário comum. Você pode fazer isso usando a variável do sistema Build.Reason. Por exemplo, adicione a seguinte condição à etapa, ao trabalho ou à fase para excluí-la das validações de solicitação de pull.

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

Comportamento dos gatilhos quando novos branches são criados

É comum configurar vários pipelines para o mesmo repositório. Por exemplo, você pode ter um pipeline para criar os documentos para seu aplicativo e outro para compilar o código-fonte. Você pode configurar gatilhos de CI com filtros de branch e filtros de caminho apropriados em cada um desses pipelines. Por exemplo, talvez você queira que um pipeline seja disparado ao enviar por push uma atualização para a pasta docs e outra para disparar quando você envia uma atualização por push para o código do aplicativo. Nesses casos, você precisa entender como os pipelines são disparados quando um novo branch é criado.

Aqui está o comportamento quando você envia por push um novo branch (que corresponde aos filtros de branch) para o repositório:

  • Se o pipeline tiver filtros de caminho, ele será disparado somente se o novo branch tiver alterações nos arquivos que correspondam a esse filtro de caminho.
  • Se o pipeline não tiver filtros de caminho, ele será disparado mesmo que não haja alterações no novo branch.

Curingas

Ao especificar um branch, uma tag ou um caminho, você pode usar um nome exato ou um curinga. Os padrões curinga permitem corresponder * a zero ou mais caracteres e ? a um determinado caractere.

  • Se você iniciar seu padrão com * em um pipeline YAML, precisará encapsular o padrão entre aspas, como "*-releases".
  • Para branches e tags:
    • Um curinga pode aparecer em qualquer lugar no padrão.
  • Para caminhos:
    • No Azure DevOps Server 2022 e superior, incluindo o Azure DevOps Services, um curinga pode aparecer em qualquer lugar dentro de um padrão de caminho e você pode usar * ou ?.
    • No Azure DevOps Server 2020 e inferior, você pode incluir * como o caractere final, mas ele não faz nada além de especificar o nome do diretório. Você pode não incluir * no meio de um filtro de caminho e talvez não use ?.
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

Gatilhos de PR

Os gatilhos de PR (solicitação de pull) fazem com que um pipeline seja executado sempre que você abrir uma solicitação de pull ou quando você envia alterações por push para ele. No Git do Azure Repos, essa funcionalidade é implementada usando políticas de branch. Para habilitar a validação de PR, navegue até as políticas de branch para o branch desejado e configure a Política de validação de build para esse branch. Para obter mais informações, confira Configurar políticas de branch.

Se você tiver uma PR aberta e enviar alterações por push ao branch de origem, vários pipelines poderão ser executados:

  • Os pipelines especificados pela política de validação de build do branch de destino serão executados no commit de mesclagem (o código mesclado entre os branches de origem e de destino da solicitação de pull), independentemente de existirem commits enviados por push cujas mensagens ou descrições contêm [skip ci] (ou qualquer uma das respectivas variantes).
  • Os pipelines disparados por alterações no branch de origem da PR, se não houver commits enviados por push cujas mensagens ou descrições contêm [skip ci] (ou qualquer uma das respectivas variantes). Se pelo menos um commit enviado por push contiver [skip ci], os pipelines não serão executados.

Por fim, depois de mesclar a PR, o Azure Pipelines executará os pipelines de CI disparados por pushes para o branch de destino, mesmo que algumas das mensagens ou descrições de commits mesclados contenham [skip ci] (ou qualquer uma das respectivas variantes).

Observação

Para configurar builds de validação para um Repositório do Git do Azure Repos, você precisa ser um administrador do projeto.

Observação

Solicitações de pull de rascunho não disparam um pipeline mesmo se você configurar uma política de branch.

Validar contribuições de forks

A criação de solicitações de pull de forks do Azure Repos não é diferente da criação de solicitações de pull no mesmo repositório ou projeto. Você pode criar forks somente na mesma organização da qual seu projeto faz parte.

Limitar o escopo de autorização do trabalho

O Azure Pipelines fornece várias configurações de segurança para configurar o escopo de autorização de trabalho com o qual os pipelines são executados.

Limitar o escopo de autorização de trabalho ao projeto atual

O Azure Pipelines fornece duas configurações Limitar o escopo de autorização de trabalho ao projeto atual:

  • Limitar o escopo da autorização de trabalho ao projeto atual para pipelines de não lançamento – essa configuração se aplica a pipelines YAML e pipelines de build clássicos. Ele não se aplica a pipelines de lançamento clássicos.
  • Limitar o escopo da autorização de trabalho ao projeto atual para pipelines de lançamento – essa configuração se aplica somente a pipelines de lançamento clássicos.

Os pipelines são executados com tokens de acesso com escopo de coleção, a menos que a configuração relevante para o tipo de pipeline esteja habilitada. As configurações Limitar o escopo de autorização de trabalho permitem reduzir o escopo de acesso de todos os pipelines para o projeto atual. Isso poderá afetar seu pipeline se você estiver acessando um Repositório do Git do Azure Repos em um projeto diferente em sua organização.

Se o seu Repositório do Git do Azure Repos estiver em um projeto diferente do pipeline e a configuração Limitar escopo de autorização de trabalho para o tipo de pipeline estiver habilitada, você precisará conceder permissão à identidade do serviço de build do pipeline para o segundo projeto. Para obter mais informações, confira Gerenciar permissões de conta de serviço de build.

O Azure Pipelines fornece uma configuração de segurança para configurar o escopo de autorização de trabalho com o qual os pipelines são executados.

  • Limitar o escopo da autorização de trabalho ao projeto atual – essa configuração se aplica a pipelines YAML e pipelines de build clássicos. Essa configuração não se aplica a pipelines de lançamento clássicos.

Os pipelines são executados com tokens de acesso com escopo de coleção, a menos que a configuração Limitar o escopo de autorização de trabalho ao projeto atual esteja habilitada. Essa configuração permite reduzir o escopo de acesso de todos os pipelines para o projeto atual. Isso poderá afetar seu pipeline se você estiver acessando um Repositório do Git do Azure Repos em um projeto diferente em sua organização.

Se seu Repositório do Git do Azure Repos estiver em um projeto diferente do pipeline e a configuração Limitar o escopo de autorização de trabalho estiver habilitada, você precisará conceder permissão à identidade do serviço de build do pipeline para o segundo projeto. Para obter mais informações, confira Escopo da autorização do trabalho.

Para obter mais informações sobre Limitar o escopo de autorização de trabalho, confira Noções básicas de tokens de acesso ao trabalho.

Limitar o escopo da autorização de trabalho para repositórios do Azure DevOps referenciados

Os pipelines podem acessar todos os repositórios do Azure DevOps em projetos autorizados, conforme descrito na seção anterior, Limitar o escopo de autorização de trabalho ao projeto atual, a menos que a configuração Limitar o escopo de autorização de trabalho para repositórios do Azure DevOps referenciados esteja habilitada. Com essa opção habilitada, você pode reduzir o escopo de acesso para todos os pipelines apenas para repositórios do Azure DevOps explicitamente referenciados por uma etapa checkout ou uma instrução uses no trabalho de pipeline que usa esse repositório.

Para definir essa configuração, navegue até Pipelines, Configurações em Configurações da organização ou em Configurações do projeto. Se habilitada no nível da organização, a configuração ficará esmaecida e indisponível no nível de configurações do projeto.

Quando Limitar o escopo de autorização de trabalho para repositórios do Azure DevOps referenciados estiver habilitada, seus pipelines YAML precisarão referenciar explicitamente todos os repositórios Git do Azure Repos que você deseja usar no pipeline como etapa de check-out no trabalho que usa o repositório. Você não poderá efetuar fetch de código usando tarefas de script e comandos git para um Repositório do Git do Azure Repos, a menos que esse repositório seja referenciado explicitamente primeiro.

Há algumas exceções em que você não precisa referenciar explicitamente um Repositório do Git do Azure Repos antes de usá-lo em seu pipeline quando a configuração Limitar o escopo de autorização de trabalho para repositórios do Azure DevOps referenciados está habilitada.

  • Se você não tiver uma etapa de check-out explícita em seu pipeline, será como se você tivesse uma etapa checkout: self e o check-out do repositório self tivesse sido feito.
  • Se você estiver usando um script para executar operações somente leitura em um repositório em um projeto público, não precisará referenciar o repositório de projeto público em uma etapa checkout.
  • Se você estiver usando um script que fornece a própria autenticação para o repositório, como um PAT, não será necessário fazer referência a esse repositório em uma etapa checkout.

Por exemplo, quando a configuração Limitar o escopo de autorização de trabalho para repositórios do Azure DevOps referenciados estiver habilitada, se o pipeline estiver no repositório FabrikamProject/Fabrikam em sua organização e você quiser usar um script para fazer check-out do repositório FabrikamProject/FabrikamTools, você precisará referenciar esse repositório em uma etapa checkout ou com uma instrução uses.

Se você já estiver verificando o repositório FabrikamTools em seu pipeline usando uma etapa de check-out, poderá usar scripts posteriormente para interagir com esse repositório.

steps:
- checkout: git://FabrikamFiber/FabrikamTools # Azure Repos Git repository in the same organization
- script: # Do something with that repo

# Or you can reference it with a uses statement in the job
uses:
  repositories: # List of referenced repositories
  - FabrikamTools # Repository reference to FabrikamTools

steps:
- script: # Do something with that repo like clone it

Observação

Para muitos cenários, o check-out de vários repositórios pode ser aproveitado, eliminando a necessidade de usar scripts para fazer check-out de repositórios adicionais em seu pipeline. Para obter mais informações, confira Fazer check-out de vários repositórios no pipeline.

Proteger o acesso a repositórios em pipelines YAML

Os pipelines podem acessar todos os repositórios do Azure DevOps em projetos autorizados, conforme descrito na seção anterior, Limitar o escopo de autorização de trabalho ao projeto atual, a menos que Proteger o acesso a repositórios em pipelines YAML esteja habilitada. Com essa opção habilitada, você pode reduzir o escopo de acesso para todos os pipelines apenas para repositórios do Azure DevOps explicitamente referenciados por uma etapa checkout ou uma instrução uses no trabalho de pipeline que usa esse repositório.

Para definir essa configuração, navegue até Pipelines, Configurações em Configurações da organização ou em Configurações do projeto. Se habilitada no nível da organização, a configuração ficará esmaecida e indisponível no nível de configurações do projeto.

Importante

A opção Proteger o acesso a repositórios em pipelines YAML é habilitada por padrão para novas organizações e projetos criados após maio de 2020. Quando Proteger o acesso a repositórios em pipelines YAML estiver habilitada, seus pipelines YAML precisarão referenciar explicitamente todos os repositórios Git do Azure Repos que você deseja usar no pipeline como etapa de check-out no trabalho que usa o repositório. Você não poderá efetuar fetch de código usando tarefas de script e comandos git para um Repositório do Git do Azure Repos, a menos que esse repositório seja referenciado explicitamente primeiro.

Há algumas exceções em que você não precisa referenciar explicitamente um Repositório do Git do Azure Repos antes de usá-lo em seu pipeline quando Proteger o acesso a repositórios em pipelines YAML está habilitado.

  • Se você não tiver uma etapa de check-out explícita em seu pipeline, será como se você tivesse uma etapa checkout: self e o check-out do repositório self tivesse sido feito.
  • Se você estiver usando um script para executar operações somente leitura em um repositório em um projeto público, não precisará referenciar o repositório de projeto público em uma etapa checkout.
  • Se você estiver usando um script que fornece a própria autenticação para o repositório, como um PAT, não será necessário fazer referência a esse repositório em uma etapa checkout.

Por exemplo, quando a configuração Proteger o acesso a repositórios em pipelines YAML estiver habilitada, se o pipeline estiver no repositório FabrikamProject/Fabrikam em sua organização e você quiser usar um script para fazer check-out do repositório FabrikamProject/FabrikamTools, você precisará referenciar esse repositório em uma etapa checkout ou com uma instrução uses.

Se você já estiver verificando o repositório FabrikamTools em seu pipeline usando uma etapa de check-out, poderá usar scripts posteriormente para interagir com esse repositório.

steps:
- checkout: git://FabrikamFiber/FabrikamTools # Azure Repos Git repository in the same organization
- script: # Do something with that repo
# Or you can reference it with a uses statement in the job
uses:
  repositories: # List of referenced repositories
  - FabrikamTools # Repository reference to FabrikamTools
steps:
- script: # Do something with that repo like clone it

Observação

Para muitos cenários, o check-out de vários repositórios pode ser aproveitado, eliminando a necessidade de usar scripts para fazer check-out de repositórios adicionais em seu pipeline. Para obter mais informações, confira Fazer check-out de vários repositórios no pipeline.

Check-out

Quando um pipeline é disparado, o Azure Pipelines efetua pull do código-fonte do Repositório do Git do Azure Repos. Você pode controlar vários aspectos de como isso acontece.

Observação

Quando você inclui uma etapa de check-out no pipeline, executamos o seguinte comando: git -c fetch --force --tags --prune --prune-tags --progress --no-recurse-submodules origin --depth=1. Se isso não atender às suas necessidades, você poderá optar por excluir o check-out interno por checkout: none e, em seguida, usar uma tarefa de script para executar seu check-out.

Versão preferencial do Git

O agente do Windows vem com uma cópia própria do Git. Se você preferir fornecer seu Git em vez de usar a cópia incluída, defina System.PreferGitFromPath como true. Essa configuração é sempre verdadeira em agentes que não são do Windows.

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

Você pode definir a configuração path na etapa Check-out do pipeline.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Submódulos

Você poderá definir a configuração submodules na etapa Check-out do pipeline se quiser baixar arquivos de submódulos.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

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 no mesmo projeto que o Repositório do Git do Azure Repos especificado acima. 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.

    • Adicionado usando uma URL relativa ao repositório main. Por exemplo

      • O check-out deste seria realizado: git submodule add ../../../FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

        Neste exemplo, o submódulo refere-se a um repositório (FabrikamFiber) na mesma organização do Azure DevOps, mas em um projeto diferente (FabrikamFiberProject). 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. Isso exige que o token de acesso ao trabalho tenha acesso ao repositório no segundo projeto. Se você tiver restringido o token de acesso ao trabalho, conforme explicado na seção acima, não poderá fazer isso. Você pode permitir que o token de acesso ao trabalho acesse o repositório no segundo projeto, (a) concedendo explicitamente acesso à conta de serviço de build do projeto no segundo projeto ou (b) usando tokens de acesso com escopo de coleção em vez de tokens com escopo de projeto para toda a organização. Para obter mais informações sobre essas opções e as respectivas implicações de segurança, confira Repositórios de acesso, artefatos e outros recursos.

      • O check-out deste não seria realizado: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

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 poderá acontecer, por exemplo, se o repositório main e os repositórios de submódulo não forem armazenados na mesma organização do Azure DevOps ou se o token de acesso ao trabalho não tiver acesso ao repositório em um projeto diferente.

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_STRING>" submodule update --init --recursive

Substitua "<BASE64_ENCODED_STRING>" pela cadeia de caracteres "pat:token" codificada 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 consigo usar um gerenciador de credenciais do Git no agente? Um: Armazenar as credenciais do submódulo em um gerenciador de credenciais do Git instalado em seu agente de compilação particular 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 builds automatizados, quando a interação do usuário não é possível.

Sincronizar tags

Importante

O recurso de marcas de sincronização tem suporte no Git do Azure Repos com o Azure DevOps Server 2022.1 e superior.

A etapa de check-out usa a opção --tags ao efetuar fetch do conteúdo de um Repositório do Git. Isso faz com que o servidor efetue fetch de todas as tags, bem como todos os objetos apontados por essas tags. Isso aumenta o tempo para executar a tarefa em um pipeline, especialmente se você tiver um repositório grande com várias tags. Além disso, a etapa de check-out sincroniza tags mesmo quando você habilita a opção de fetch superficial, anulando a utilidade dela. Para reduzir a quantidade de dados buscados ou extraídos de um Repositório do Git, a Microsoft adicionou uma nova opção de check-out para controlar o comportamento das tags de sincronização. Essa opção está disponível em pipelines clássicos e YAML.

Se as tags devem ou não ser sincronizadas ao fazer check-out de um repositório é algo que pode ser configurado no YAML pela definição da propriedade fetchTags e na interface do usuário pela configuração Sincronizar tags.

Você pode definir a configuração fetchTags na etapa Check-out do pipeline.

Para definir a configuração no YAML, defina a propriedade fetchTags.

steps:
- checkout: self
  fetchTags: true

Você também pode definir essa configuração usando a opção Sincronizar tags na interface do usuário das configurações do pipeline.

  1. Edite seu pipeline YAML e escolha Mais ações, Gatilhos.

    Captura de tela do menu mais gatilhos.

  2. Escolha YAML, Obter fontes.

    Captura de tela de Obter fontes.

  3. Defina a configuração Sincronizar tags.

    Captura de tela da configuração Sincronizar tags.

Observação

Se você definir fetchTags explicitamente em sua etapa checkout, essa configuração terá prioridade sobre a configuração definida na interface do usuário das configurações do pipeline.

Comportamento padrão

  • Para pipelines existentes criados antes do lançamento do Azure DevOps sprint 209, lançado em setembro de 2022, o padrão para sincronizar marcas permanece o mesmo que o comportamento existente antes da adição das opções Sincronizar tags, que é true.
  • Para novos pipelines criados após a versão 209 do Azure DevOps sprint, o padrão para sincronizar tags é false.

Observação

Se você definir fetchTags explicitamente em sua etapa checkout, essa configuração terá prioridade sobre a configuração definida na interface do usuário das configurações do pipeline.

Fetch superficial

Talvez você queira limitar de quão anteriormente 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.

Importante

Novos pipelines criados após a atualização do Azure DevOps sprint 209 de setembro de 2022 têm o fetch superficial habilitado por padrão e configurado com uma profundidade de 1. Anteriormente, o padrão não era efetuar fetch superficialmente. Para verificar seu pipeline, exiba a configuração Fetch superficial na interface do usuário das configurações do pipeline, conforme descrito na seção a seguir.

Você pode definir a configuração fetchDepth na etapa Check-out do pipeline.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Você também pode configurar a profundidade do fetch definindo a opção Profundidade superficial na interface do usuário das configurações do pipeline.

  1. Edite seu pipeline YAML e escolha Mais ações, Gatilhos.

    Captura de tela do menu mais gatilhos.

  2. Escolha YAML, Obter fontes.

    Captura de tela de Obter fontes.

  3. Defina a configuração Fetch superficial. Desmarque Fetch superficial para desabilitar o fetch superficial ou marque a caixa e insira uma Profundidade para habilitar o fetch superficial.

    Captura de tela das opções.

Observação

Se você definir fetchDepth explicitamente em sua etapa checkout, essa configuração terá prioridade sobre a configuração definida na interface do usuário das configurações do pipeline. A configuração de fetchDepth: 0 efetua fetch de todo o histórico e substitui a configuração Fetch superficial.

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 pipeline é iniciado, o branch a ser compilado é resolvido para uma ID de 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.

Não sincronizar fontes

Talvez você queira ignorar o fetch de novos commits. 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.

Você pode definir a configuração Não sincronizar fontes na etapa Check-out do pipeline definindo checkout: none.

steps:
- checkout: none  # Don't sync sources

Observação

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

Limpar build

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.

Você pode definir a configuração clean na etapa Check-out do pipeline.

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

Quando clean é definido como true, 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

Para obter mais opções, você pode definir a configuração workspace de um Trabalho.

jobs:
- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  ...
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

Isso fornece as opções de limpeza a seguir.

  • outputs: a mesma operação que a configuração clean descrita na tarefa de check-out anterior 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.

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

  • all: 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.

No momento, não é possível definir essa configuração no YAML, mas você pode fazer isso no editor clássico. Ao editar um pipeline YAML, você pode acessar o editor clássico escolhendo Gatilhos no menu do editor YAML.

Configurar opções do Git, YAML.

No editor clássico, escolha YAML, escolha a tarefa Obter fontes e configure lá as propriedades desejadas.

No editor Clássico, escolha YAML > Obter fontes.

Em Formato de tag, 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.

Perguntas frequentes

Os problemas relacionados à integração Azure Repos se enquadram em três categorias:

  • Gatilhos com falha: meu pipeline não está sendo disparado quando efetuo push de uma atualização para o repositório.
  • Check-out com falha: meu pipeline está sendo disparado, mas ele falha na etapa de check-out.
  • Versão errada: meu pipeline é executado, mas está usando uma versão inesperada da fonte/YAML.

Gatilhos com falha

Acabei de criar um Pipeline YAML novo com gatilhos de CI/PR, mas o pipeline não está sendo disparado.

Siga cada uma destas etapas para solucionar problemas dos gatilhos com falha:

  • Você está configurando o gatilho de PR no arquivo YAML ou em políticas de branch para o repositório? Para um Repositório do Git do Azure Repos, não é possível configurar um gatilho de PR no arquivo YAML. Você precisa usar políticas de branch.

  • Seu pipeline está em pausa ou desabilitado? Abra o editor do pipeline e selecione Configurações para verificar. Se o pipeline estiver em pausa ou desabilitado, os gatilhos não funcionarão.

  • Você atualizou o arquivo YAML no branch correto? Se você enviar por push uma atualização para um branch, o arquivo YAML nesse mesmo branch controlará o comportamento de CI. Se você enviar por push uma atualização para um branch de origem, o arquivo YAML resultante da mesclagem do branch de origem com o branch de destino controlará o comportamento de PR. Verifique se o arquivo YAML no branch correto tem a configuração necessária de CI ou PR.

  • Você configurou o gatilho corretamente? Ao definir um gatilho YAML, você pode especificar cláusulas include e exclude para branches, tags e caminhos. Verifique se a cláusula include corresponde aos detalhes do commit e se a cláusula exclude não os exclui. Verifique a sintaxe dos gatilhos e verifique se ela é precisa.

  • Você usou variáveis para definir o gatilho ou os caminhos? Observe que não há suporte para isso.

  • Você usou modelos para seu arquivo YAML? Nesse caso, verifique se os gatilhos estão definidos no arquivo YAML principal. Não há suporte para gatilhos definidos dentro de arquivos de modelo.

  • Você excluiu os branches ou caminhos para os quais você efetuou push das alterações? Teste enviando uma alteração por push para um caminho incluído em um branch incluído. Observe que os caminhos nos gatilhos diferenciam maiúsculas de minúsculas. Certifique-se de usar a mesma formatação de maiúsculas e minúsculas das pastas reais ao especificar os caminhos nos gatilhos.

  • Você acabou de efetuar push de um novo branch? Nesse caso, o novo branch pode não iniciar uma nova execução. Confira a seção "Comportamento dos gatilhos quando novos branches são criados".

Meus gatilhos de CI ou PR vinham funcionando bem. No entanto, eles pararam de funcionar agora.

Primeiro, siga as etapas de solução de problemas na pergunta anterior. Em seguida, siga estas etapas adicionais:

  • Você tem conflitos de mesclagem em sua PR? Para uma PR que não disparou um pipeline, abra-a e verifique se ela tem um conflito de mesclagem. Resolva o conflito de mesclagem.

  • Você está enfrentando um atraso no processamento de eventos de push ou PR? Normalmente, você pode verificar isso conferindo se o problema é específico para um determinado pipeline ou se é comum a todos os pipelines ou repositórios em seu projeto. Caso uma atualização de push ou PR para qualquer um desses repositórios apresente esse sintoma, podemos estar enfrentando atrasos no processamento dos eventos de atualização. Verifique se estamos enfrentando uma interrupção de serviço em nossa página de status. Se a página de status mostra um problema, isso significa necessariamente que nossa equipe já começou a trabalhar nele. Verifique a página com frequência para obter atualizações sobre o problema.

Não quero que os usuários substituam a lista de branches para gatilhos quando atualizarem o arquivo YAML. Como posso fazer isso?

Os usuários com permissões para contribuir com código podem atualizar o arquivo YAML e incluir/excluir branches adicionais. Como resultado, os usuários podem incluir um recurso ou branch de usuário próprio no arquivo YAML deles e efetuar push dessa atualização para um recurso ou branch de usuário. Isso pode fazer com que o pipeline seja disparado para todas as atualizações desse branch. Se você quiser evitar esse comportamento, poderá:

  1. Editar o pipeline na interface do usuário do Azure Pipelines.
  2. Navegar até o menu Gatilhos.
  3. Selecionar Substituir o gatilho de integração contínua YAML aqui.
  4. Especifique os branches a serem incluídos ou excluídos para o gatilho.

Quando você segue essas etapas, todos os gatilhos de CI especificados no arquivo YAML são ignorados.

Tenho vários repositórios no meu pipeline YAML. Como fazer configurar gatilhos para cada repositório?

Consulte gatilhos em Usando vários repositórios.

Check-out com falha

Vejo o seguinte erro no arquivo de log durante a etapa de check-out. Como corrigi-la?

remote: TF401019: The Git repository with name or identifier XYZ does not exist or you do not have permissions for the operation you are attempting.
fatal: repository 'XYZ' not found
##[error] Git fetch failed with exit code: 128

Siga cada uma destas etapas para solucionar problemas de seu check-out com falha:

  • O repositório ainda existe? Primeiro, verifique se ele faz isso abrindo-o na página Repos.

  • Você está acessando o repositório usando um script? Em caso afirmativo, marque a configuração Limitar o escopo da autorização de trabalho para repositórios do Azure DevOps referenciados. Quando Limitar o escopo de autorização de trabalho a repositórios do Azure DevOps referenciados estiver habilitada, você não poderá fazer check-out de repositórios Git do Azure Repos usando um script, a menos que eles sejam explicitamente referenciados primeiro no pipeline.

  • Qual é o escopo de autorização de trabalho do pipeline?

    • Se o escopo é de coleção:

      • Isso pode ser um erro intermitente. Execute novamente o pipeline.
      • Alguém pode ter removido o acesso à conta do Serviço de Build da Coleção de Projetos.
        • Acesse Configurações do projeto para o projeto no qual o repositório existe. Selecione Repos > Repositórios > repositório específico e Segurança.
        • Verifique se o Serviço de Build da Coleção de Projetos (nome-da-coleção) existe na lista de usuários.
        • Verifique se essa conta tem acesso para Criação de tag e Leitura.

    • Se o escopo for projeto:

      • O repositório está no mesmo projeto que o pipeline?
        • Sim:
          • Isso pode ser um erro intermitente. Execute novamente o pipeline.
          • Alguém pode ter removido o acesso à conta do Serviço de Build do Projeto.
            • Acesse Configurações do projeto para o projeto no qual o repositório existe. Selecione Repos > Repositórios > repositório específico e Segurança.
            • Verifique se o Serviço de Build do nome-do-projeto (nome-da-coleção) existe na lista de usuários.
            • Verifique se essa conta tem acesso para Criação de tag e Leitura.
        • Não:

Versão errada

Uma versão errada do arquivo YAML está sendo usada no pipeline. Por quê?

  • Para gatilhos de CI, o arquivo YAML que está no branch que você está enviando por push é avaliado para ver se um build de CI deve ser executado.
  • Para gatilhos de PR, o arquivo YAML resultante da mesclagem dos branches de origem e destino da PR é avaliado para ver se um build de PR deve ser executado.