Solucionar problemas de pipelines

Azure DevOps Serviços | 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 logs na página de resumo da execução do pipeline para resolver o problema. Este guia fornece instruções para diagnosticar falhas de pipeline usando logs, 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.

Ver registros

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

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

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

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

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

Captura de ecrã das opções de visualização de registo no Azure DevOps.

Analise 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 do 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 erros . 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 do pipeline.

Captura de ecrã do ícone de análise de visualização para Azure DevOps Server.

Escolha View agent para agentes auto-hospedados (ou About hosted agent image para agentes hospedados pela Microsoft) para visualizar mais informações sobre o agente usado para executar o pipeline e View log para visualizar os logs de execução do pipeline.

Captura de ecrã da página de análise de erros no portal Azure DevOps.

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

Captura de ecrã dos detalhes da tarefa a partir 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 for aparente na página de resumo da execução do pipeline ou na navegação nos logs, verifique a seção Problemas comuns a seguir e consulte Revisar logs para diagnosticar problemas do pipeline para obter informações sobre como baixar logs completos que incluem mais informações de diagnóstico.

Problemas comuns

Informações de tarefas para execuções de pipeline com falha

Azure DevOps fornece uma definição Task Insights for Failed Pipeline Runs, que, quando ativada, fornece notificações pop-up de falhas de compilação com um link para visualizar um relatório.

Captura de ecrã das métricas de insights de tarefas.

Para definir essa configuração, navegue até Visualizar recursos, localize Task Insights for Failed Pipeline Runs, e escolha a configuração desejada.

Captura de ecrã da configuração de insights de tarefas para execuções falhadas de pipeline.

Notificações para execuções com falha

O Azure DevOps inclui notificações integradas para execuções falhadas de pipeline. Para ativar notificações:

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

Captura de tela de 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 pipeline não parecer 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 uma autorização para ser executado por um recurso, como uma conexão de serviço ou pool de agentes.

  1. Vá para o pipeline e inicie manualmente uma execução.
  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.

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

Há duas maneiras de autorizar pipelines para acessar seu pool de agentes.

Autorizar pipelines específicos

Você pode autorizar individualmente pipelines específicos para execução em um grupo 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 manualmente da lista autorizada executando o procedimento a seguir. Este procedimento é realizado ao nível do projeto na sua organização Azure DevOps.

  1. No Azure DevOps, vai a Definições do projeto, Pool de agentes, escolhe o teu pool auto-hospedado e escolhe Segurança.
  2. Escolha + para adicionar um pipeline à lista autorizada.
  3. Escolha X(Revogar acesso) para remover um pipeline da lista autorizada.

Configurar o acesso aberto

Alguns recursos permitem configurar o acesso aberto para que cada nova definição de pipeline não exija autorização explícita.

A configuração do acesso aberto requer permissões de administrador do projeto .

Para configurar o acesso aberto para pools de agentes:

  1. No Azure DevOps, vai a Definições do projeto, Pool de agentes, escolhe o teu pool auto-hospedado e escolhe Segurança.
  2. Escolha Mais ações, Acesso aberto, para habilitar o acesso aberto e escolha Acesso aberto novamente para confirmar.
  3. Para revogar o acesso aberto, escolha Restringir permissão.

Para rever se Acesso Aberto está disponível para outros tipos recursos, consulte Gerir a segurança em Azure Pipelines e procure por Acesso Aberto.

Para obter mais informações sobre 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 da tarefa

Um pipeline pode ser executado por um longo tempo e, em seguida, falhar devido ao tempo limite do trabalho. O tempo limite do trabalho depende muito do agente que está sendo usado. Os agentes alojados gratuitos da Microsoft têm um tempo limite máximo de 60 minutos por tarefa 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 seguintes.

  • Compre um agente hospedado pela Microsoft que lhe dê 360 minutos para todos os trabalhos, independentemente do repositório usado
  • Utilizar um agente autoalojado para evitar quaisquer problemas de tempo limite causados pelo agente

Saiba mais sobre o tempo limite de trabalho.

Observação

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

Problemas ao transferir código

O meu pipeline está a falhar numa etapa de checkout

Se estiver a usar uma etapa checkout num repositório Azure Repos Git na sua organização, que esteja num projeto diferente do seu pipeline, certifique-se de que a definição Limitar o âmbito de autorização do trabalho ao projeto atual está desativada, ou siga os passos em Identificações de build com escopo para garantir que o seu pipeline tem acesso ao repositório.

Quando seu pipeline não puder acessar o repositório devido ao escopo limitado de autorização de trabalho, você receberá 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, certifique-se de que os nomes do repositório e do projeto estejam corretos na etapa ou na declaração de recurso do repositório.

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

Obter fontes que não baixam alguns arquivos

Poderá ver uma mensagem no registo "Todos os ficheiros atualizados" do comando tf get. Verifique se a identidade de serviço interna tem permissão para baixar as fontes. A identidade Project Collection Build Service ou Project Build Service precisa 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 web do controlo de versões, pode navegar pelos ficheiros do projeto em qualquer nível da hierarquia de pastas e verificar as definições de segurança.

Obtenha fontes através do Team Foundation Proxy

A forma mais fácil de configurar o agente para obter fontes através de um Proxy Team Foundation é definir variáveis TFSPROXY de ambiente que apontem para o servidor proxy TFVC para a execução do agente como utilizador.

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

O meu pipeline está a falhar numa etapa de linha de comando, como o MSBUILD

É útil restringir se uma falha de compilação ou de lançamento resulta de um problema de produto do Azure Pipelines (agente ou tarefas). Falhas de compilação e lançamento também podem resultar de comandos externos.

Verifique nos logs a linha de comando exata executada pela tarefa com falha. Tentar executar o comando localmente a partir da linha de comando pode reproduzir o problema. Pode ser útil executar o comando localmente a partir da sua própria máquina e/ou iniciar sessão na máquina e executar o comando como a conta de serviço.

Por exemplo, o problema está a acontecer durante a parte do MSBuild do seu pipeline de compilação (por exemplo, está a usar a tarefa MSBuild ou Visual Studio Build)? Em caso afirmativo, tente executar o mesmo comando MSBuild em uma máquina local usando os mesmos argumentos. Se você pode reproduzir o problema em uma máquina local, então suas próximas etapas são investigar o problema MSBuild .

Layout do arquivo

O local das ferramentas, bibliotecas, cabeçalhos e outras coisas necessárias para uma compilação pode ser diferente no agente hospedado do que na sua máquina local. Se uma compilação falhar porque não consegue encontrar um desses arquivos, você pode usar os scripts abaixo para inspecionar o layout no agente. Isso pode ajudá-lo a rastrear o arquivo ausente.

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

# 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 uma máquina local e quando uma compilação ou versão está sendo executada em um agente. Se o agente estiver configurado para correr como um serviço no Linux, macOS ou Windows, então não está a correr numa sessão interativa com um utilizador autenticado. Sem uma sessão interativa ligada, existem limitações na interação com a interface do utilizador, entre outras.

Erros de ficheiros ou pastas em utilização

File or folder in use Os erros são indicados por mensagens de erro, tais 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 [...]

Passos de resolução de problemas:

Detetar arquivos e pastas em uso

No Windows, ferramentas como Process Monitor podem capturar um rasto de eventos de ficheiro sob um diretório específico. Ou, para uma captura de momento, ferramentas como Process Explorer ou Handle podem ser usadas.

Exclusão de antivírus

O software antivírus que analisa os seus ficheiros pode causar erros de ficheiros ou pastas durante uma compilação ou lançamento, e as compilações podem demorar mais tempo a concluir. Adicionar exclusões de antivírus para os seus diretórios e processos de agentes auto-hospedados pode ajudar a resolver estes problemas.

Advertência

Excluir ficheiros ou processos da análise antivírus pode tornar o seu dispositivo ou dados mais vulneráveis. Avalia os riscos e exclua apenas caminhos em que tenhas confiança que são seguros.

Processos a excluir:

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

Diretórios a excluir (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
  • Construa pastas de saída configuradas para os seus pipelines, como diretórios intermédios, locais de armazenamento de artefactos 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 mais informações, consulte Exclusões de varredura antivírus.

MSBuild e /nodeReuse:false

Se você invocar o MSBuild durante a compilação, certifique-se de passar o argumento /nodeReuse:false (forma /nr:falsecurta). 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 na expectativa de uma potencial construção subsequente.

Este recurso do MSBuild pode interferir com as 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á acrescentam /nr:false aos argumentos passados ao MSBuild. No entanto, se você invocar o MSBuild a partir de seu próprio script, precisará especificar o argumento.

MSBuild e /maxcpucount:[n]

Por defeito, as tarefas de build como MSBuild e Visual Studio Build executam o MSBuild com o switch /m. Em alguns casos, isso pode causar problemas, como vários problemas de acesso a arquivos de processo.

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

Problemas com ficheiros em uso podem resultar ao utilizar o recurso de processo concorrente do MSBuild. Não especificar o argumento /maxcpucount:[n] (forma /m:[n]curta) instrui o MSBuild a usar apenas um único processo. Se estiveres a usar as tarefas MSBuild ou Visual Studio Build, podes precisar de especificar "/m:1" para sobrepor o argumento "/m" que é adicionado por defeito.

Falhas intermitentes ou inconsistentes de MSBuild

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

O processo deixa de responder

O processo para de responder causas e 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 a partir da 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 a necessidade de programas solicitarem entrada. Por exemplo, no .NET, os programas podem confiar no Booleano System.Environment.UserInteractive para determinar se devem exibir um aviso. Quando o agente está a correr como um serviço Windows, o valor é falso.

Despejo de processo

Analisar um despejo do processo pode ajudar a identificar o que um processo bloqueado está esperando.

Projeto WiX

A criação de um projeto WiX quando os loggers MSBuild personalizados estão habilitados pode fazer com que o WiX bloqueie à espera do fluxo de saída. Adicionar o argumento /p:RunWixToolsOutOfProc=true MSBuild adicional resolve o problema.

Terminações de linhas para várias plataformas

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

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

* text eol=lf

Variáveis com ' (aspas simples) adicionadas

Se o pipeline incluir um script Bash que define variáveis usando o ##vso comando, você poderá ver outro ' anexado ao valor da variável definida. Tal ocorre devido a uma interação com set -x. A solução é desativar set -x temporariamente antes de definir uma variável. A sintaxe do Bash para o fazer é 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. Bash rastreia exatamente qual comando foi executado e ecoa-o para stdout. Isso faz com que o agente veja o ##vso comando duas vezes e, na segunda vez, Bash terá adicionado o ' personagem ao 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 para o valor correto, "my_value". No entanto, quando vê a segunda linha, o agente processa tudo até ao fim da linha. MY_VAR está definido como "my_value'".

As bibliotecas não são instaladas para aplicações Python quando o script é executado

Quando uma aplicação Python é implementada, em alguns casos, um pipeline CI/CD é executado e o código é implementado com sucesso, mas o ficheiro requirements.txt responsável por instalar todas as bibliotecas de dependências não é executado.

Para instalar as dependências, use um script pós-implantação na tarefa de implantação do App Service. 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, consulte Solução de problemas de conexão de serviço. Para solucionar problemas específicos de conexões de serviço usando identidade de carga de trabalho para autenticação, consulte Solucionar problemas de conexões de serviço de identidade de carga de trabalho.

Pipeline deixou de receber informações do 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 de Sprint 228, os registos Azure Pipelines contêm métricas de utilização de recursos para cada etapa.

Ao usar Azure DevOps Services, pode ver a utilização de recursos nos registos, incluindo a utilização de disco, memória e CPU, ao ativar registos detalhados. Quando o pipeline for concluído, procure nos logs para Agent environment resources cada uma das etapas.

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.

Permita Storage Explorer implementar conteúdos estáticos como .css e .js para um site estático a partir de Azure DevOps via Azure Pipelines

Neste cenário, pode usar a tarefa Azure File Copy para carregar conteúdo no site. Você pode usar qualquer uma das ferramentas descritas em Carregamento de conteúdo para carregar conteúdo para o contentor Web.

Próximo passo

  • Revise os logs para descobrir ferramentas de diagnóstico adicionais.
  • Last updated on