Solucionar problemas nas execuções de pipeline

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

Se a execução do pipeline não for concluída, use as informações de diagnóstico e os registros na página de resumo da execução do pipeline para solucionar o problema. Este guia fornece instruções para diagnosticar falhas no pipeline usando registros, ferramentas de análise de erros e técnicas comuns de solução de problemas. Saiba como identificar as causas principais e implementar soluções para manter seus pipelines funcionando sem problemas.

Captura de tela da página de resumo da execução do pipeline com informações de diagnóstico.

Exibir logs

Selecione a mensagem de erro para visualizar os registros da tarefa que não foi concluída.

Captura de tela de uma mensagem de erro de tarefa na página de resumo da execução do pipeline.

A página de registros mostra o erro selecionado. Neste exemplo, há um erro na tarefa cmd-line, em que o comando echo é inserido como ech.

Captura de tela do log de diagnóstico para a execução de pipeline.

Você pode exibir o log bruto da tarefa escolhendo Exibir log bruto e pode pesquisar o log usando Localizar.

Captura de tela das opções de exibição de log no Azure DevOps.

Examine os logs da tarefa com falha em busca de informações de erro e pistas sobre por que a tarefa está falhando. Por padrão, os logs não detalhados são gerados por uma execução de pipeline. Se os logs padrão não indicarem a causa do problema, você poderá obter mais informações configurando logs detalhados.

Página de análise de erros

A assistência para solução de problemas está disponível usando a página Análise de erro. Mova o mouse sobre a linha de informações de erro e escolha o ícone Exibir análise.

Captura de tela do ícone de análise de exibição na página de resumo de execução de pipeline.

Screenshot do ícone de análise visual para Azure DevOps Server.

Escolha Exibir agente para agentes auto-hospedados (ou Sobre a imagem do agente hospedado para agentes hospedados pela Microsoft) para exibir mais informações sobre o agente usado para executar o pipeline e Exibir log para exibir os logs de execução do pipeline.

Screenshot da página de análise de erros em Azure DevOps portal.

Escolha o nome da tarefa abaixo dos Detalhes de tempo de execução para exibir informações sobre a tarefa.

Captura de tela dos detalhes da tarefa da análise de erros.

Neste exemplo, você pode ver que há um erro no Value do Script. Escolha Sobre esta tarefa para exibir a documentação da tarefa.

Se o problema não estiver aparente na página de resumo da execução do pipeline ou na navegação dos registros, verifique a seção Problemas comuns e consulte Analisar os registros para diagnosticar problemas no pipeline para obter informações sobre o download de registros completos que incluem mais informações de diagnóstico.

Problemas comuns

Insights de tarefa para execuções de pipeline com falha

O Azure DevOps fornece uma configuração de Informações sobre Tarefas para Execuções de Pipeline com Falha, que, quando habilitada, fornece notificações pop-up de falhas de compilação com um link para exibir um relatório.

Captura de tela das métricas de insights da tarefa.

Para definir essa configuração, navegue até Visualizar recursos, localize Task Insights para Execuções de Pipeline Com Falha e escolha a configuração desejada.

Captura de tela dos insights de tarefa para a configuração de execuções de pipeline com falha.

Notificações para execuções com falha

Azure DevOps inclui notificações integradas para execuções de pipeline com falha. Para ativar as notificações:

  1. Vá para Configurações do projeto>Notificações do seu projeto.
  2. Escolha o tipo de notificação que você deseja receber. Para receber notificação sempre que houver falha em uma execução de pipeline, selecione Uma compilação falha.

Captura de tela das notificações nas configurações do projeto.

Esse pipeline precisa de permissão para acessar um recurso antes que essa execução possa continuar

Se o seu pipeline não iniciar ou se você receber uma mensagem de erro como This pipeline needs permission to access a resource before this run can continue, verifique se o pipeline está aguardando autorização para ser executado por um recurso, como uma conexão de serviço ou um pool de agentes.

  1. Acesse o pipeline e inicie uma execução manualmente.
  2. A mensagem Este pipeline precisa de permissão para acessar um recurso antes que essa execução possa continuar é exibida. Selecione Exibir ao lado da mensagem.
  3. Na tela Aguardando revisão, selecione Permitir e, na tela de confirmação, selecione Permitir novamente.

Essa ação adiciona explicitamente o pipeline como um usuário autorizado do recurso.

Existem duas maneiras de autorizar pipelines a acessar seu pool de agentes.

  • Autorizar pipelines específicos — Autorize individualmente pipelines específicos de um projeto do Azure DevOps para serem executados no pool.
  • Configurar o acesso aberto – Configurar um pool de agentes no nível do projeto para estar disponível para todos os pipelines nesse projeto.

Autorizar pipelines específicos

Você pode autorizar individualmente pipelines específicos para serem executados em um pool de agentes seguindo o procedimento na seção anterior quando receber uma mensagem como This pipeline needs permission to access a resource before this run can continue.

Você também pode adicionar e remover pipelines da lista de autorizados manualmente, executando o seguinte procedimento. Este procedimento é executado no nível do projeto em sua organização Azure DevOps.

  1. Em Azure DevOps, vá para Project settings, Agent pools, escolha seu pool auto-hospedado e escolha Security.
  2. Escolha + para adicionar um pipeline à lista de autorizados.
  3. Escolha X(Revogar acesso) para remover um pipeline da lista autorizada.

Configurar o acesso aberto

Alguns recursos permitem que você configure o Acesso Aberto para que cada nova definição de pipeline não exija autorização explícita.

A configuração do Open Access requer permissões de administrador do Project .

Para configurar o Open Access para pools de agentes:

  1. Em Azure DevOps, vá para Project settings, Agent pools, escolha seu pool auto-hospedado e escolha Security.
  2. Escolha Mais ações, Abra o acesso, para habilitar o acesso aberto e escolha Abrir acesso novamente para confirmar.
  3. Para revogar o acesso aberto, escolha Restringir permissão.

Para examinar se Open access está disponível para outros tipos de recursos, consulte Gerenciar segurança no Azure Pipelines e procure por Open access.

Para obter mais informações sobre o acesso aberto para pools de agentes, consulte Definir permissões de pipeline para um pool de agentes individuais e permissões de pipeline.

Tempo limite do trabalho

Um pipeline pode ser executado por um longo tempo e, em seguida, falhar devido ao tempo limite do trabalho ser atingido. O tempo limite do trabalho depende muito do agente que está sendo usado. Os agentes hospedados gratuitos da Microsoft têm um tempo limite máximo de 60 minutos por trabalho para um repositório privado e 360 minutos para um repositório público.

Para aumentar o tempo limite máximo de um trabalho, você pode optar por qualquer um dos itens a seguir.

  • Compre um agente hospedado pela Microsoft, que oferece 360 minutos para todos os trabalhos, independentemente do repositório usado
  • Usar um agente auto-hospedado para descartar quaisquer problemas de tempo limite devido ao agente

Saiba mais sobre o tempo limite do trabalho.

Observação

Se os trabalhos do agente hospedado pela Microsoft estiverem atingindo o tempo limite, verifique se o tempo limite do pipeline está definido com um valor maior do que o tempo limite máximo de um trabalho. Para verificar, confira Tempos limite.

Problemas ao baixar o código

Meu pipeline está falhando em uma etapa de check-out

Se você estiver usando uma etapa checkout em um repositório Git do Azure Repos em sua organização que esteja em um projeto diferente do seu pipeline, certifique-se de que a configuração Limitar escopo de autorização de trabalho ao projeto atual esteja desabilitada ou siga as etapas em Identidades de construção com escopo para garantir que seu pipeline tenha acesso ao repositório.

Quando o pipeline não puder acessar o repositório devido ao escopo de autorização de trabalho limitado, você recebe o erro Git fetch failed with exit code 128 e seus logs conterão uma entrada semelhante a Remote: TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting.

Se o pipeline estiver falhando imediatamente com Could not find a project that corresponds with the repository, verifique se o nome do projeto e do repositório está correto na etapa checkout ou na declaração de recurso do repositório.

Problemas no Controle de Versão do Team Foundation (TFVC)

Obter fontes que não baixam alguns arquivos

Talvez você veja uma mensagem no registro "Todos os arquivos atualizados" do comando tf get. Verifique se a identidade de serviço interna tem permissão para baixar as fontes. Ou a identidade Serviço de construção de coleção de projetos ou Serviço de construção de projetos precisam de permissão para baixar os códigos-fonte, dependendo do escopo de autorização selecionado na guia Geral do pipeline de compilação. Na interface do usuário da Web do controle de versão, você pode navegar pelos arquivos do projeto em qualquer nível da hierarquia de pastas e verificar as configurações de segurança.

Obter fontes pelo Proxy do Team Foundation

A maneira mais fácil de configurar o agente para obter fontes por meio de um Proxy do Team Foundation é definir variáveis TFSPROXY de ambiente que apontam para o servidor proxy TFVC para a execução do agente como usuário.

Windows:

    set TFSPROXY=http://tfvcproxy:8081
    setx TFSPROXY=http://tfvcproxy:8081 // If the agent service is running as NETWORKSERVICE or any service account you can't easily set user level environment variable

macOS/Linux:

    export TFSPROXY=http://tfvcproxy:8081

Meu pipeline está falhando em uma etapa da linha de comando, como MSBUILD

É útil restringir se uma falha de build ou de versão é o resultado de um problema com o produto do Azure Pipelines (agente ou tarefas). Falhas de build e versão também podem resultar de comandos externos.

Verifique os logs para obter a linha de comando exata executada pela tarefa com falha. A tentativa de executar o comando localmente na linha de comando pode reproduzir o problema. Pode ser útil executar o comando localmente em seu próprio computador e/ou entrar no computador e executar o comando como a conta de serviço.

Por exemplo, o problema está acontecendo durante a parte do MSBuild do pipeline de build (por exemplo, você está usando a tarefa MSBuild ou Build do Visual Studio )? Nesse caso, tente executar o mesmo comando do MSBuild em um computador local usando os mesmos argumentos. Se você puder reproduzir o problema no computador local, as próximas etapas serão investigar o problema do MSBuild.

Layout do arquivo

O local das ferramentas, bibliotecas, cabeçalhos e outras coisas necessárias para um build pode ser diferente no agente hospedado do que no computador local. Se um build falhar porque não consegue encontrar um desses arquivos, você poderá usar os scripts abaixo para inspecionar o layout no agente. Isso pode ajudar você a rastrear o arquivo ausente.

Crie um novo pipeline YAML em um local temporário (por exemplo, um novo repositório criado para solução de problemas). Conforme escrito, o script pesquisa diretórios em seu caminho. Opcionalmente, você pode editar a linha SEARCH_PATH= para pesquisar em outros locais.

# Script for Linux and macOS
pool: { vmImage: ubuntu-latest } # or whatever pool you use
steps:
- checkout: none
- bash: |
    SEARCH_PATH=$PATH  # or any colon-delimited list of paths
    IFS=':' read -r -a PathDirs <<< "$SEARCH_PATH"
    echo "##[debug] Found directories"
    for element in "${PathDirs[@]}"; do
        echo "$element"
    done;
    echo;
    echo;  
    echo "##[debug] Found files"
    for element in "${PathDirs[@]}"; do
        find "$element" -type f
    done

# Script for Windows
pool: { vmImage: windows-2019 } # or whatever pool you use
steps:
- checkout: none
- powershell: |
    $SEARCH_PATH=$Env:Path
    Write-Host "##[debug] Found directories"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Write-Host "$Dir"
    }
    Write-Host ""
    Write-Host ""
    Write-Host "##[debug] Found files"
    ForEach ($Dir in $SEARCH_PATH -split ";") {
      Get-ChildItem $Dir -File -ErrorAction Continue | ForEach-Object -Process {
        Write-Host $_.FullName
      }
    }

Diferenças entre o prompt de comando local e o agente

Tenha em mente que algumas diferenças estão em vigor ao executar um comando em um computador local e quando um build ou versão está em execução em um agente. Se o agente estiver configurado para ser executado como um serviço no Linux, macOS ou Windows, ele não será executado em uma sessão interativa de logon. Sem uma sessão de logon interativa, há interação com a interface do usuário e outras limitações.

Erros do arquivo ou pasta em uso

File or folder in use Os erros geralmente são indicados por mensagens de erro, como:

  • Access to the path [...] is denied.
  • The process cannot access the file [...] because it is being used by another process.
  • Access is denied.
  • Can't move [...] to [...]

Etapas para solucionar problemas:

Detectar arquivos e pastas em uso

Em Windows, ferramentas como Process Monitor podem capturar um registro de eventos de arquivo em um diretório específico. Ou, por um instantâneo no tempo, ferramentas como Explorador de Processos ou Identificador podem ser usadas.

Exclusão do antivírus

A verificação de arquivos por software antivírus pode causar erros de arquivo ou pasta em uso durante uma compilação ou lançamento, e as compilações podem demorar mais para serem concluídas. Adicionar exclusões de antivírus para seus diretórios e processos de agente autogerenciados podem ajudar a resolver esses problemas.

Aviso

A exclusão de arquivos ou processos da verificação antivírus pode tornar seu dispositivo ou dados mais vulneráveis. Avalie os riscos e exclua apenas os caminhos que você está confiante de que estão seguros.

Processos a serem excluídos:

  • Agent.Listener.exe
  • Agent.Worker.exe
  • AgentService.exe

Diretórios a serem excluídos (e seus subdiretórios):

  • O diretório de instalação do agente (por exemplo, C:\agent ou /home/user/myagent)
  • A pasta de trabalho do agente: <agent_directory>\_work
  • A pasta de diagnóstico do agente: <agent_directory>\_diag
  • Pastas de saída de compilação configuradas para seus pipelines, como diretórios de preparação, locais de entrega de artefatos e caminhos de publicação de símbolos.
  • %ProgramFiles%\Microsoft Visual Studio\<VersionNumber> (Windows)
  • C:\Windows\Microsoft.NET\Framework\<VersionNumber>\Temporary ASP.NET Files (Windows)
  • C:\Windows\Microsoft.NET\Framework64\<VersionNumber>\Temporary ASP.NET Files (Windows)

Para obter mais informações, consulte exclusões de verificação de antivírus.

MSBuild e /nodeReuse:false

Se você invocar o MSBuild durante o build, passe o argumento /nodeReuse:false (forma curta /nr:false). Caso contrário, os processos do MSBuild continuarão em execução após a conclusão da compilação. Os processos permanecem por algum tempo em antecipação a uma possível compilação subsequente.

Esse recurso do MSBuild pode interferir nas tentativas de excluir ou mover um diretório, devido a um conflito com o diretório de trabalho dos processos do MSBuild.

As tarefas msbuild e Visual Studio build já adicionam /nr:false aos argumentos passados para o MSBuild. No entanto, se você invocar o MSBuild de seu próprio script, será necessário especificar o argumento.

MSBuild e /maxcpucount:[n]

Por padrão, as tarefas de build, como MSBuild e Visual Studio Build executar o MSBuild com a opção /m. Em alguns casos, isso pode causar problemas de acesso a arquivos de vários processos.

Tente adicionar o argumento /m:1 às tarefas de build para forçar o MSBuild a executar apenas um processo por vez.

Problemas de arquivo em uso podem ocorrer ao aproveitar o recurso de processo simultâneo do MSBuild. Não especificar o argumento /maxcpucount:[n] (forma curta /m:[n]) instrui o MSBuild a usar apenas um único processo. Se você estiver usando as tarefas msbuild ou Visual Studio build, talvez seja necessário especificar "/m:1" para substituir o argumento "/m" que é adicionado por padrão.

Falhas inconsistentes ou intermitentes do MSBuild

Se você estiver enfrentando falhas intermitentes ou inconsistentes do MSBuild, tente instruir o MSBuild a usar apenas um único processo. Erros intermitentes ou inconsistentes podem indicar que sua configuração de destino é incompatível com o recurso de processo simultâneo do MSBuild. Confira MSBuild e /maxcpucount:[n].

O processo para de responder

O processo interrompe as causas de resposta e as etapas de solução de problemas:

Aguardando entrada

Um processo que para de responder pode indicar que um processo está aguardando entrada.

Executar o agente na linha de comando de uma sessão interativa conectada pode ajudar a identificar se um processo está solicitando uma caixa de diálogo para entrada.

Executar o agente como um serviço pode ajudar a eliminar programas de solicitação de entrada. Por exemplo, no .NET, os programas podem depender do Boolean System.Environment.UserInteractive para determinar se o prompt deve ser solicitado. Quando o agente está em execução como um serviço de Windows, o valor é falso.

Despejo de processo

A análise de um despejo do processo pode ajudar a identificar o que um processo com deadlock está aguardando.

Projeto WiX

A criação de um projeto WiX quando agentes personalizados do MSBuild estão habilitados pode fazer com que o WiX faça deadlock aguardando o fluxo de saída. Adição do argumento adicional do MSBuild /p:RunWixToolsOutOfProc=true contorna o problema.

Terminações de linha para várias plataformas

Ao executar pipelines em várias plataformas, às vezes você pode encontrar problemas com terminações de linha diferentes. Historicamente, o Linux e o macOS usavam caracteres de avanço de linha (LF), enquanto o Windows usava um retorno de carro mais um avanço de linha (CRLF). O Git tenta compensar a diferença fazendo com que as linhas terminem automaticamente em LF no repositório, mas CRLF no diretório de trabalho em Windows.

A maioria das ferramentas do Windows funciona bem com finais apenas em LF, o que pode fazer com que esse comportamento automático cause mais problemas do que resolva. Se você encontrar problemas com base em terminações de linha, recomendamos que você configure o Git para preferir LF em todos os lugares. Para fazer isso, adicione um arquivo .gitattributes à raiz do repositório. Nesse arquivo, adicione a seguinte linha:

* text eol=lf

Variáveis com ' (aspas simples) anexadas

Se o seu pipeline incluir um script Bash que define variáveis usando o comando ##vso, você poderá ver outro ' anexado ao valor da variável que você definiu. Isso ocorre devido a uma interação com set -x. A solução é desabilitar set -x temporariamente antes de definir uma variável. A sintaxe do Bash para fazer isso é set +x.

set +x
echo ##vso[task.setvariable variable=MY_VAR]my_value
set -x

Por que isso acontece?

Muitos scripts Bash incluem o comando set -x para ajudar na depuração. O Bash rastreia exatamente o comando que foi executado e o ecoa no stdout. Isso faz com que o agente veja o comando ##vso duas vezes, e, na segunda vez, o Bash terá adicionado o caractere ' no final.

Por exemplo, considere este pipeline:

steps:
- bash: |
    set -x
    echo ##vso[task.setvariable variable=MY_VAR]my_value

No stdout, o agente vê duas linhas:

##vso[task.setvariable variable=MY_VAR]my_value
+ echo '##vso[task.setvariable variable=MY_VAR]my_value'

Quando o agente vir a primeira linha, MY_VAR será definido como o valor correto, "my_value". No entanto, quando vê a segunda linha, o agente processa tudo até o final da linha. MY_VAR é definido como "my_value'".

Bibliotecas não são instaladas para Python aplicativo quando o script é executado

Quando um aplicativo Python é implantado, em alguns casos, um pipeline de CI/CD é executado e o código é implantado com êxito, mas o arquivo requirements.txt responsável pela instalação de todas as bibliotecas de dependência não é executado.

Para instalar as dependências, use um script pós-implantação na tarefa de implantação do Serviço de Aplicativo. O exemplo a seguir mostra o comando que você deve usar no script pós-implantação. Você pode atualizar o script para seu cenário.

D:\home\python364x64\python.exe -m pip install -r requirements.txt

Para solucionar problemas relacionados a conexões de serviço, confira Solução de problemas de conexão de serviço. Para solucionar problemas específicos de conexões de serviço usando a identidade da carga de trabalho para autenticação, consulte Solucionar problemas de conexões de serviço de identidade de carga de trabalho.

Pipeline parou de ouvir o agente

Se o pipeline falhar com uma mensagem como We stopped hearing from agent <agent name>. Verify the agent machine is running and has a healthy network connection., verifique a utilização de recursos do agente para ver se a máquina do agente está ficando sem recursos. A partir do Sprint 228, os logs Azure Pipelines contêm métricas de utilização de recursos para cada etapa.

Ao usar o Azure DevOps Services, você pode ver o uso dos recursos nos logs, incluindo uso de disco, uso de memória e utilização da CPU, habilitando logs detalhados. Quando o pipeline for concluído, pesquise entradas nos logsAgent environment resources para cada etapa.

2024-02-28T17:41:15.1315148Z ##[debug]Agent environment resources - Disk: D:\ Available 12342.00 MB out of 14333.00 MB, Memory: Used 1907.00 MB out of 7167.00 MB, CPU: Usage 17.23%

Para obter informações sobre como capturar logs de utilização de recursos adicionais, consulte Capturar detalhes de utilização de recursos.

Habilite Storage Explorer para implantar conteúdo estático como .css e .js em um site estático de Azure DevOps via Azure Pipelines

Nesse cenário, você pode usar a tarefa Azure File Copy para enviar conteúdo para o site. Você pode usar qualquer uma das ferramentas descritas em Carregar conteúdo para carregar conteúdo no contêiner da Web.

Próxima etapa

  • Last updated on