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

  • Artigo

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

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

Escolha um repositório para construir

Você cria um novo 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 self repositório. Por padrão, esse é o repositório que seu pipeline cria.

Mais tarde, você pode configurar seu pipeline para fazer check-out de um repositório diferente ou de vários repositórios. Para saber como fazer isso, consulte Checkout multi-repo.

Os Pipelines do Azure devem ter acesso aos seus repositórios para acionar suas compilações e buscar seu código durante as compilações. Normalmente, um pipeline tem acesso a repositórios no mesmo projeto. Mas, se você deseja acessar repositórios em um projeto diferente, então você precisa atualizar as permissões concedidas aos tokens de acesso de trabalho.

Desencadeadores de IC

Os gatilhos de integração contínua (CI) fazem com que um pipeline seja executado sempre que você envia uma atualização para as ramificações especificadas ou envia tags especificadas.

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 Desabilitar gatilho de CI YAML implícito, introduzida no sprint 227 do Azure DevOps, esteja habilitada. A configuração Desabilitar gatilho YAML CI implícito pode ser configurada no nível da organização ou no nível do projeto. Quando a configuração Desabilitar gatilho YAML CI implícito está habilitada, os gatilhos CI para pipelines YAML não são habilitados se o pipeline YAML não tiver uma trigger seção. Por padrão, Desativar gatilho CI YAML implícito não está habilitado.

Ramos

Você pode controlar quais ramificações obtêm gatilhos de CI com uma sintaxe simples:

trigger:
- main
- releases/*

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

Nota

Não é possível usar variáveis em gatilhos, pois as variáveis são avaliadas em tempo de execução (depois que o gatilho é acionado).

Nota

Se você usar modelos para criar arquivos YAML, só poderá especificar gatilhos no arquivo YAML principal para o pipeline. Não é possível especificar gatilhos nos arquivos de modelo.

Para gatilhos mais complexos que usam exclude ou batch, você deve 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á acionado se uma alteração for enviada por push para main ou para qualquer ramificação de liberações. No entanto, ele não será acionado se uma alteração for feita em uma ramificação de versões que comece com old.

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

Além de especificar nomes de ramificações nas branches listas, 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 Desativar gatilho YAML CI implícito não estiver habilitada, o padrão será como se você tivesse escrito:

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 somente os pushes para ramificações explicitamente configuradas para serem incluídas acionarão um pipeline. As inclusões são processadas primeiro e, em seguida, as exclusões são removidas dessa lista.

Execução de CI em lote

Se você tiver muitos membros da equipe carregando alterações com frequência, convém 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, em seguida, 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

Nota

batch não é suportado em gatilhos de recursos do repositório.

Para esclarecer este exemplo, digamos que um empurrão A para main fez com que o gasoduto acima funcionasse. Enquanto esse pipeline está em execução, envios B adicionais ocorrem no C 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.

Nota

Se o pipeline tiver vários trabalhos e estágios, a primeira execução ainda deverá atingir um estado terminal completando ou ignorando todos os seus trabalhos e estágios antes que a segunda execução possa ser iniciada. Por esse motivo, você deve ter cuidado ao usar esse recurso em um pipeline com vários estágios ou aprovações. Se você deseja agrupar suas compilações em lote nesses casos, é recomendável dividir seu processo de CI/CD em dois pipelines - um para compilação (com lote) e outro para implantações.

Caminhos

Você pode especificar caminhos de arquivo para incluir ou excluir.

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

Ao especificar caminhos, você deve especificar explicitamente ramificações para acionar se estiver usando o Azure DevOps Server 2019.1 ou inferior. Não é possível acionar um pipeline com apenas um filtro de caminho; Você também deve ter um filtro de ramificação e os arquivos alterados que correspondem ao filtro de caminho devem ser de uma ramificação que corresponda ao filtro de ramificação. Se você estiver usando o Azure DevOps Server 2020 ou mais recente, poderá omitir branches o filtro em todas as ramificações em conjunto com o filtro de caminho.

Cartões curinga são suportados para filtros de caminho. Por exemplo, você pode incluir todos os caminhos que correspondem ao 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á implicitamente incluída 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. Certifique-se de usar o mesmo caso que as pastas reais.
  • Não é possível usar variáveis em caminhos, pois as variáveis são avaliadas em tempo de execução (após o disparador ter sido acionado).

Etiquetas

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

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

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

Importante

Se você especificar tags em combinação com filtros de ramificação, o gatilho será acionado se o filtro de ramificação estiver satisfeito ou se o filtro de tags estiver satisfeito. Por exemplo, se uma tag push satisfizer o filtro de ramificação, o pipeline será acionado mesmo se a tag for excluída pelo filtro de tag, porque o push satisfez o filtro de ramificação.

Optar por não participar na IC

Desativando o gatilho de IC

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

# A pipeline with no CI trigger
trigger: none

Importante

Quando você envia uma alteração para uma ramificação, o arquivo YAML nessa ramificação é avaliado para determinar se uma execução de CI deve ser iniciada.

Ignorando IC para pushes individuais

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

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

  • [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

É um cenário comum executar diferentes etapas, trabalhos ou estágios em seu pipeline, dependendo do tipo de gatilho que iniciou a execução. Você pode fazer isso usando a variável Build.Reasonde sistema . Por exemplo, adicione a seguinte condição à sua etapa, trabalho ou estágio para excluí-la das validações de RP.

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

Comportamento de gatilhos quando novas ramificações são criadas

É 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 criar o código-fonte. Você pode configurar gatilhos de CI com filtros de ramificação e filtros de caminho apropriados em cada um desses pipelines. Por exemplo, você pode querer que um pipeline seja acionado quando você enviar uma atualização por push para a pasta e outro para disparar quando você enviar por push uma atualização para o código do docs aplicativo. Nesses casos, você precisa entender como os pipelines são acionados quando uma nova ramificação é criada.

Aqui está o comportamento quando você envia uma nova ramificação (que corresponde aos filtros de ramificação) para o repositório:

  • Se o pipeline tiver filtros de caminho, ele será acionado somente se a nova ramificação tiver alterações em arquivos que correspondam a esse filtro de caminho.
  • Se o pipeline não tiver filtros de caminho, ele será acionado mesmo que não haja alterações na nova ramificação.

Carateres universais

Ao especificar uma ramificação, marca ou caminho, você pode usar um nome exato ou um curinga. Os padrões curinga permitem * corresponder a zero ou mais caracteres e corresponder a um único caractere ? .

  • Se você iniciar seu padrão com * em um pipeline YAML, deverá envolver o padrão entre aspas, como "*-releases".
  • Para ramificações e tags:
    • Um curinga pode aparecer em qualquer lugar no padrão.
  • Para caminhos:
    • No Azure DevOps Server 2022 e superior, incluindo os Serviços de DevOps do Azure, 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 diferente de especificar o nome do diretório por si só. Você não pode incluir * no meio de um filtro de caminho e não pode usar ?o .
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

Gatilhos de RP

Os gatilhos de solicitação pull (PR) fazem com que um pipeline seja executado sempre que você abre uma solicitação pull ou quando você envia alterações para ele. No Azure Repos Git, essa funcionalidade é implementada usando políticas de filial. Para habilitar a validação de RP, navegue até as políticas de ramificação para a ramificação desejada e configure a política de validação de compilação para essa ramificação. Para obter mais informações, consulte Configurar políticas de filial.

Se você tiver uma RP aberta e enviar alterações para sua ramificação de origem, vários pipelines poderão ser executados:

  • Os pipelines especificados pela política de validação de compilação da ramificação de destino serão executados na confirmação de mesclagem (o código mesclado entre as ramificações de origem e de destino da solicitação pull), independentemente de existirem confirmações enviadas cujas mensagens ou descrições contenham [skip ci] (ou qualquer uma de suas variantes).
  • Os pipelines acionados por alterações na ramificação de origem do PR, se não houver commits push cujas mensagens ou descrições contenham [skip ci] (ou qualquer uma de suas variantes). Se pelo menos uma confirmação enviada contiver [skip ci], os pipelines não serão executados.

Finalmente, depois de mesclar a RP, os Pipelines do Azure executarão os pipelines de CI acionados por pushes para a ramificação de destino, mesmo que algumas das mensagens ou descrições das confirmações mescladas contenham [skip ci] (ou qualquer uma de suas variantes).

Nota

Para configurar compilações de validação para um repositório Git do Azure Repos, você deve ser um administrador de projeto de seu projeto.

Nota

As solicitações pull de rascunho não acionam um pipeline, mesmo se você configurar uma política de ramificação.

Validar contribuições de forks

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

Limitar o escopo de autorização de trabalho

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

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

O Azure Pipelines fornece dois Limitar o escopo de autorização de trabalho às configurações atuais do projeto :

  • Limitar o escopo de autorização de trabalho ao projeto atual para pipelines sem liberação - Esta configuração se aplica a pipelines YAML e pipelines de compilação clássicos. Essa configuração não se aplica a pipelines de liberação clássicos.
  • Limitar o escopo de autorização de trabalho ao projeto atual para pipelines de liberação - Esta configuração se aplica apenas aos pipelines de liberação 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 escopo de autorização de trabalho permitem reduzir o escopo de acesso de todos os pipelines ao projeto atual. Isso pode afetar seu pipeline se você estiver acessando um repositório Git do Azure Repos em um projeto diferente em sua organização.

Se o repositório 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ê deverá conceder permissão à identidade do serviço de compilação para seu pipeline para o segundo projeto. Para obter mais informações, consulte Gerenciar permissões de conta de serviço de compilação.

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

  • Limitar o escopo de autorização de trabalho ao projeto atual - Esta configuração se aplica a pipelines YAML e pipelines de construção clássicos. Essa configuração não se aplica a pipelines de liberação clássicos.

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

Se o repositório Git do Azure Repos estiver em um projeto diferente do pipeline e a configuração Limitar escopo de autorização de trabalho estiver habilitada, você deverá conceder permissão à identidade do serviço de compilação para seu pipeline para o segundo projeto. Para obter mais informações, veja Âmbito de autorização de tarefas.

Para obter mais informações sobre Limitar o escopo de autorização de trabalho, consulte Entender os tokens de acesso ao trabalho.

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

Os pipelines podem acessar qualquer repositório de DevOps do Azure em projetos autorizados, conforme descrito na seção anterior Limitar o escopo de autorização de trabalho ao projeto atual, a menos que Limitar o escopo de autorização de trabalho aos repositórios de DevOps do Azure referenciados esteja habilitado. Com essa opção habilitada, você pode reduzir o escopo de acesso para todos os pipelines para apenas repositórios de DevOps do Azure explicitamente referenciados por uma checkout etapa ou uma uses instrução 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 Configurações do projeto. Se habilitada no nível da organização, a configuração ficará acinzentada e indisponível no nível de configurações do projeto.

Quando Limitar o escopo de autorização de trabalho a repositórios de DevOps do Azure referenciados estiver habilitado, seus pipelines YAML devem fazer referência explícita a quaisquer repositórios Git do Azure Repos que você deseja usar no pipeline como uma etapa de check-out no trabalho que usa o repositório. Você não poderá buscar código usando tarefas de script e comandos git para um repositório Git do Azure Repos, a menos que esse repositório seja referenciado explicitamente pela primeira vez.

Há algumas exceções em que você não precisa fazer referência explícita a um repositório Git do Azure Repos antes de usá-lo em seu pipeline quando Limitar o escopo de autorização de trabalho a repositórios de DevOps do Azure referenciados estiver habilitado.

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

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

Se você já estiver fazendo check-out do FabrikamTools repositório em seu pipeline usando uma etapa de check-out, poderá usar scripts subsequentemente 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

Nota

Para muitos cenários, o checkout multi-repo 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, consulte Verificar vários repositórios em seu pipeline.

Proteja o acesso a repositórios em pipelines YAML

Os pipelines podem acessar qualquer repositório de DevOps do Azure 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 habilitado. Com essa opção habilitada, você pode reduzir o escopo de acesso para todos os pipelines para apenas repositórios de DevOps do Azure explicitamente referenciados por uma checkout etapa ou uma uses instrução 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 Configurações do projeto. Se habilitada no nível da organização, a configuração ficará acinzentada e indisponível no nível de configurações do projeto.

Importante

Proteger o acesso a repositórios em pipelines YAML está habilitado 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 está habilitado, seus pipelines YAML devem fazer referência explícita a quaisquer repositórios Git do Azure Repos que você deseja usar no pipeline como uma etapa de check-out no trabalho que usa o repositório. Você não poderá buscar código usando tarefas de script e comandos git para um repositório Git do Azure Repos, a menos que esse repositório seja referenciado explicitamente pela primeira vez.

Há algumas exceções em que você não precisa fazer referência explícita a um repositório Git do Azure Repos antes de usá-lo em seu pipeline quando Proteger o acesso a repositórios em pipelines YAML estiver habilitado.

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

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

Se você já estiver fazendo check-out do FabrikamTools repositório em seu pipeline usando uma etapa de check-out, poderá usar scripts subsequentemente 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

Nota

Para muitos cenários, o checkout multi-repo 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, consulte Verificar vários repositórios em seu pipeline.

Finalização da Compra

Quando um pipeline é acionado, o Azure Pipelines extrai seu código-fonte do repositório Git do Azure Repos. Você pode controlar vários aspetos de como isso acontece.

Nota

Quando você inclui uma etapa de checkout em seu 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ê pode optar por excluir o check-out interno e checkout: none , em seguida, usar uma tarefa de script para executar seu próprio checkout.

Versão preferida do Git

O agente do Windows vem com sua própria cópia do Git. Se você preferir fornecer seu próprio 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 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

Você pode definir a path configuração na etapa Checkout do seu 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ê pode definir a submodules configuração na etapa Checkout 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 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 que o repositório Git do Azure Repos especificado acima. 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.

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

      • Este seria verificado: 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 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. Isso requer que o token de acesso ao trabalho tenha acesso ao repositório no segundo projeto. Se você restringiu 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 concedendo explicitamente acesso à conta de serviço de compilação 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 suas implicações de segurança, consulte Acessar repositórios, artefatos e outros recursos.

      • Este não seria verificado: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

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

Certifique-se de substituir "<BASE64_ENCODED_STRING>" pela sua cadeia de caracteres "pat:token" codificada 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.

Sincronizar tags

Importante

O recurso de marcas de sincronização é suportado no Azure Repos Git com o Azure DevOps Server 2022.1 e superior.

A etapa de checkout usa a --tags opção ao buscar o conteúdo de um repositório Git. Isso faz com que o servidor busque 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 checkout sincroniza as tags mesmo quando você ativa a opção de busca superficial, possivelmente derrotando seu propósito. Para reduzir a quantidade de dados buscados ou extraídos de um repositório Git, a Microsoft adicionou uma nova opção de checkout para controlar o comportamento de sincronização de tags. Esta opção está disponível em pipelines clássicos e YAML.

A sincronização de tags ao fazer check-out de um repositório pode ser configurada no YAML definindo a fetchTags propriedade e na interface do usuário definindo a configuração Sincronizar marcas .

Você pode definir a fetchTags configuração na etapa Checkout do seu pipeline.

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

steps:
- checkout: self
  fetchTags: true

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

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

    Captura de tela do menu de mais gatilhos.

  2. Escolha YAML, Obter fontes.

    Captura de tela de Obter fontes.

  3. Configure a configuração Sincronizar marcas .

    Captura de ecrã da definição Sincronizar etiquetas.

Nota

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

Comportamento predefinido

Nota

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

Busca rasa

Você pode querer limitar o tempo de volta no histórico para baixar. 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.

Importante

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

Você pode definir a fetchDepth configuração na etapa Checkout do seu 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 de busca definindo a opção Profundidade superficial na interface do usuário de configurações do pipeline.

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

    Captura de tela do menu de mais gatilhos.

  2. Escolha YAML, Obter fontes.

    Captura de tela de Obter fontes.

  3. Configure a configuração de busca superficial. Desmarque a busca superficial para desativar a busca superficial ou marque a caixa e insira uma Profundidade para habilitar a busca superficial.

    Captura de ecrã das opções.

Nota

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

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 o pipeline é iniciado, a ramificação a ser criada é 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.

Não sincronizar fontes

Você pode querer pular a busca de novas confirmações. 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 apenas executar automação (por exemplo, alguns scripts) que não dependem de código no controle de versão.

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

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

Nota

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

Construção limpa

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.

Você pode definir a clean configuração na etapa Checkout do seu 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 está definido como true o pipeline de compilação executa um desfazer de quaisquer alterações no $(Build.SourcesDirectory). Mais especificamente, os seguintes comandos do Git são executados antes de buscar a fonte.

git clean -ffdx
git reset --hard HEAD

Para obter mais opções, você pode definir a workspace configuração 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 dá as seguintes opções de limpeza.

  • saídas: mesma operação que a configuração de limpeza descrita na tarefa de checkout anterior, além de: Exclui e recria $(Build.BinariesDirectory). Observe que o e $(Common.TestResultsDirectory) são sempre excluídos e recriados antes de cada compilação, $(Build.ArtifactStagingDirectory) independentemente de qualquer uma dessas configurações.

  • recursos: exclui e recria $(Build.SourcesDirectory). Isso resulta na inicialização de um novo repositório Git local para cada compilação.

  • all: Exclui e recria $(Agent.BuildDirectory). Isso resulta na inicialização de um novo repositório Git local para cada compilação.

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.

No momento, você não pode definir essa configuração no YAML, mas pode fazê-lo no editor clássico. Ao editar um pipeline YAML, você pode acessar o editor clássico escolhendo Triggers no menu do editor YAML.

Configure as opções do Git, YAML.

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

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

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

FAQ

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

  • Gatilhos com falha: Meu pipeline não está sendo acionado quando envio uma atualização para o repositório.
  • Falha no check-out: Meu pipeline está sendo acionado, mas falha na etapa de checkout.
  • Versão errada: Meu pipeline é executado, mas está usando uma versão inesperada do source/YAML.

Gatilhos com falha

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

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

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

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

  • Você atualizou o arquivo YAML na ramificação correta? Se você enviar uma atualização para uma ramificação, o arquivo YAML nessa mesma ramificação governará o comportamento de CI. Se você enviar uma atualização para uma ramificação de origem, o arquivo YAML resultante da mesclagem da ramificação de origem com a ramificação de destino governará o comportamento de RP. Certifique-se de que o arquivo YAML na ramificação correta tem a configuração de CI ou PR necessária.

  • Você configurou o gatilho corretamente? Ao definir um gatilho YAML, você pode especificar cláusulas de inclusão e exclusão para ramificações, tags e caminhos. Certifique-se de que a cláusula include corresponda aos detalhes da sua confirmação e que a cláusula de exclusão não os exclua. Verifique a sintaxe dos gatilhos e certifique-se de que está correta.

  • Você usou variáveis na definição do gatilho ou dos caminhos? Isso não é apoiado.

  • Você usou modelos para o seu arquivo YAML? Em caso afirmativo, certifique-se de que seus gatilhos estão definidos no arquivo YAML principal. Não há suporte para gatilhos definidos dentro de arquivos de modelo.

  • Excluiu os ramos ou caminhos para os quais empurrou as suas mudanças? Teste empurrando uma alteração para um caminho incluído em uma ramificação incluída. Observe que os caminhos nos gatilhos diferenciam maiúsculas de minúsculas. Certifique-se de usar o mesmo caso que os de pastas reais ao especificar os caminhos em gatilhos.

  • Você acabou de empurrar um novo ramo? Em caso afirmativo, a nova ramificação pode não iniciar uma nova execução. Consulte a seção "Comportamento dos gatilhos quando novas ramificações são criadas".

Meus gatilhos de CI ou RP têm funcionado bem. Mas, eles pararam de trabalhar agora.

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

  • Tem conflitos de fusão no seu PR? Para um PR que não acionou um pipeline, abra-o e verifique se ele tem um conflito de mesclagem. Resolva o conflito de mesclagem.

  • Você está enfrentando um atraso no processamento de eventos push ou PR? Normalmente, você pode verificar isso vendo se o problema é específico de um único pipeline ou é comum a todos os pipelines ou repositórios em seu projeto. Se um push ou uma atualização de RP para qualquer um dos repositórios apresentar esse sintoma, podemos estar enfrentando atrasos no processamento dos eventos de atualização. Verifique se estamos passando por uma interrupção de serviço em nossa página de status. Se a página de status mostrar um problema, nossa equipe já deve ter começado a trabalhar nele. Verifique a página com frequência para atualizações sobre o problema.

Não quero que os usuários substituam a lista de ramificações para gatilhos quando atualizarem o arquivo YAML. Como posso fazê-lo?

Os usuários com permissões para contribuir com código podem atualizar o arquivo YAML e incluir/excluir ramificações adicionais. Como resultado, os usuários podem incluir seu próprio recurso ou ramificação de usuário em seu arquivo YAML e enviar essa atualização para um recurso ou ramificação de usuário. Isso pode fazer com que o pipeline seja acionado para todas as atualizações dessa ramificação. Se você quiser evitar esse comportamento, então você pode:

  1. Edite o pipeline na interface do usuário do Azure Pipelines.
  2. Navegue até o menu Triggers .
  3. Selecione Substituir o gatilho de integração contínua YAML a partir daqui.
  4. Especifique as ramificações a serem incluídas ou excluídas 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 devo proceder para configurar acionadores para cada repositório?

Veja acionadores em Utilizar vários repositórios.

Falha no checkout

Vejo o seguinte erro no arquivo de log durante a etapa de checkout. Como faço para corrigi-lo?

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 check-out com falha:

  • O repositório ainda existe? Primeiro, certifique-se de que o faz, abrindo-o na página Repos .

  • Você está acessando o repositório usando um script? Em caso afirmativo, verifique a configuração Limitar o escopo de autorização de trabalho aos repositórios de DevOps do Azure referenciados. Quando Limitar o escopo de autorização de trabalho a repositórios de DevOps do Azure referenciados estiver habilitado, você não poderá fazer check-out dos 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 for coleta:

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

    • Se o escopo for projeto:

      • O recompra está no mesmo projeto que o pipeline?
        • Sim:
          • Este pode ser um erro intermitente. Execute novamente o pipeline.
          • Alguém pode ter removido o acesso à conta do Project Build Service.
            • Vá para Configurações do projeto no qual o repositório existe. Selecione Repositório específico de repositórios > de recompras > e, em seguida, Segurança.
            • Verifique se o serviço de compilação your-project-name (your-collection-name) existe na lista de usuários.
            • Verifique se essa conta tem a tag Criar e o acesso de leitura .
        • Não:
          • O seu pipeline está em um projeto público?

Versão errada

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

  • Para gatilhos de CI, o arquivo YAML que está na ramificação que você está enviando é avaliado para ver se uma compilação de CI deve ser executada.
  • Para gatilhos PR, o arquivo YAML resultante da fusão das ramificações de origem e destino do PR é avaliado para ver se uma compilação PR deve ser executada.