Depurador de Pipeline do GitHub Actions

Visão Geral

Esta habilidade foi projetada para atuar como um diagnóstico especialista em CI/CD. Ela se concentra especificamente em ler logs brutos de falhas do GitHub Actions, identificar a causa raiz do travamento ou falha e gerar as alterações precisas em YAML ou código necessárias para corrigir o pipeline.

Quando Usar

• Use quando um fluxo de trabalho do GitHub Actions falhar inesperadamente e o log de erro for longo, obscuro ou enganoso.
• Use ao depurar erros de incompatibilidade de dependências, segredos ausentes, problemas de cache ou problemas de ambiente do executor em CI.
• Use para otimizar pipelines lentos, identificando gargalos nas etapas do fluxo de trabalho.
• Use para atualizar e modernizar ações ou sintaxe de fluxo de trabalho desatualizadas.

Como Funciona

1. Ingestão e Redação de Logs: Analise o log do fluxo de trabalho do GitHub Actions fornecido (geralmente exportado como um arquivo de texto bruto ou colado diretamente). REQUISITO DE SEGURANÇA CRÍTICO: O usuário/agente deve redigir todas as credenciais sensíveis, segredos, tokens, chaves privadas e caminhos de sistema internos dos logs antes de colá-los ou carregá-los.
2. Mapeamento de Contexto: Cruze o ponto de falha com a etapa e o trabalho específicos na definição .github/workflows/*.yml.
3. Análise da Causa Raiz: Identifique se a falha se deve a:
   • Segredos ausentes ou mal configurados (${{ secrets.API_KEY }}).
   • Incompatibilidades de versão do ambiente Node/Python/OS.
   • Testes instáveis ou limites de tempo limite.
   • Erros de sintaxe em scripts bash executados dentro do bloco run:.
   • Versões de ação inválidas ou ações desatualizadas.
4. Proposta de Resolução: Forneça uma diff direta do arquivo .yml ou do script subjacente que precisa ser modificado.

Melhores Práticas

• Forneça Contexto Completo: Sempre revise tanto a definição do fluxo de trabalho (arquivo .yml) quanto o log de falha simultaneamente para garantir um diagnóstico preciso.
• Verifique as Versões das Ações: Muitas falhas são causadas por versões de tempo de execução desatualizadas (por exemplo, Node.js 16) em ações de terceiros mais antigas (por exemplo, actions/checkout@v2). Inspecione os requisitos do executor instalado e a versão da ação suportada, verifique as alterações upstream e fixe o SHA do commit completo revisado. Não assuma que um exemplo histórico v4 é o mais recente.
• Auditoria de Permissões: Certifique-se de que o fluxo de trabalho tenha o bloco permissions: correto se estiver tentando escrever no repositório, pacotes ou implantar ambientes.
• Reprodutibilidade: Se um teste falhar em CI, mas passar localmente, investigue as diferenças de ambiente, como fuso horário, estado do navegador sem cabeça, limites de memória ou condições de corrida de execução paralela.

Exemplos

Exemplo 1: Corrigindo um Erro de Versão Desatualizada de Ação do Node.js

Log com Falha:

Warning: The Go/Node.js/Python version used by this action is deprecated.
Error: Node.js 16 actions are deprecated. Please update to use Node.js 20.

Diferença da Correção Proposta:

       - name: Checkout Code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4

Exemplo 2: Diagnosticando e Corrigindo um Segredo de Repositório Ausente

Log com Falha:

Run npm run deploy
  npm run deploy
  shell: /usr/bin/bash -e {0}
Error: API Key is required for deployment. Process exited with code 1.

Diferença da Correção Proposta:

       - name: Deploy App
         run: npm run deploy
+        env:
+          DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}

Vinculação Exata de Execução

Registre o repositório, o ID da execução, a tentativa, o evento, o SHA do HEAD, o executor e a etapa com falha. Leia o fluxo de trabalho e os scripts referenciados do mesmo commit, não apenas do main atual. Separe erros de origem, permissões, ferramentas ausentes e tempos limite de observação. Nunca enfraqueça testes ou verificações necessárias para obter um selo verde.

Notas de Segurança e Proteção

• Exposição de Credenciais e Redação de Logs Brutos: Sob nenhuma circunstância logs brutos contendo segredos não mascarados, URLs privadas, destinos de implantação ou tokens devem ser processados sem redação prévia. Sempre garanta que o usuário ou agente redija todas as informações sensíveis antes da ingestão.
• Modo de Teste (Dry-Run): Ao recomendar modificações em etapas de script bash dentro de fluxos de trabalho, certifique-se de sugerir a adição de sinalizadores como --dry-run ou a execução em estágio, sempre que possível, para evitar efeitos colaterais não intencionais em ambientes downstream durante a depuração.

Limitações

• A habilidade não pode ler segredos de repositório de forma segura. Ela só pode inferir segredos ausentes ou malformados se o log reclamar de variáveis de ambiente indefinidas ou falhas de autenticação.

…