gha-doctor

gha-doctor é uma ferramenta de linha de comando que diagnostica workflows do GitHub Actions por jobs falhos, minutos desperdiçados, etapas lentas, problemas de cache e anti-padrões de workflow em um único comando e com zero configuração. O README o posiciona ao lado do actionlint (correção) e do zizmor (segurança), cobrindo velocidade, custo e confiabilidade. Ele lê .github/workflows para verificações estáticas e usa um GITHUB_TOKEN existente ou autenticação via gh CLI para análise de histórico de execuções; um modo apenas para lint funciona offline sem autenticação. Uma flag --repo owner/name busca os arquivos de workflow e histórico de execuções de outro repositório por meio da API, então os repositórios não precisam ser clonados, e --org executa triagem em frotas de toda uma organização ou usuário. A análise estática é organizada em 21 regras documentadas (D001 a D021) com severidades e números de linha apontando para a localização exata no YAML. Elas abrangem questões como falta de concorrência com cancel-in-progress em workflows de pull request, jobs sem timeout-minutes, setup-node/setup-python/setup-java sem o input built-in de cache, checkouts de histórico completo, crons mais frequentes que a cada 15 minutos, runners macOS e Windows em todo push, docker build-push sem cache-from, actions/cache sem restore-keys, continue-on-error em nível de job, retenção padrão de artefatos, matrizes grandes, npm install em vez de npm ci, gatilhos duplos unscoped push plus pull_request, cron no minuto 0, labels de runners desligados ou aposentados e versões de ações, atualizações automatizadas de pin de ações ausentes, comandos de workflow obsoletos, runtimes de Node obsoletos em ações publicadas e workflows agendados sem proteção de repositório. As descobertas podem ser silenciadas inline com um comentário na linha sinalizada ou globalmente com --disable, e cada regra pode ser explicada offline com --explain. A análise de histórico de execuções detecta jobs falhos ao procurar jobs que falharam e passaram no mesmo commit, relata taxa de sucesso por workflow, durações p50 e p95, tempo de fila e custo, identifica as etapas mais lentas e minutos desperdiçados, e pode medir taxas de hit e miss de cache e nomear testes falhos a partir dos logs de job. Tudo o que é medido se consolida em uma pontuação de saúde detalhada de 0 a 100 que pode ser escrita como um badge SVG. Os formatos de saída incluem texto puro, JSON legível por máquina com JSON Schemas publicados, Markdown, SARIF 2.1.0, comandos de workflow de anotação inline e um relatório HTML autossuficiente com gráficos embutidos. Um modo de auto-correção aplica edições cirúrgicas por linha nas regras corrigíveis, com um modo diff separado para visualizar alterações sem gravar. Um arquivo de config de repositório em .gha-doctor.yml ou .github/gha-doctor.yml define políticas como regras desabilitadas, tamanho da amostra de histórico, amostragem de logs e limiares de falha; flags explícitas do CLI têm precedência e uma flag no-config a ignora. O código de saída 2 sinaliza avisos para que a ferramenta possa fazer gate de CI, com gating configurável de severidade e um limiar mínimo de pontuação de saúde. O projeto também vem como uma ação composta do GitHub que instala o binário de release e oferece inputs para args, versão, token, resumo de job, comentários sticky de pull-request, comparação diff de baseline contra um branch base e limiares de falha; anotações inline estão habilitadas por padrão. O GitHub Enterprise Server é suportado pela variável GH_HOST. Um modo stdio server do Model Context Protocol expõe seis ferramentas apenas para leitura (analyze_repo, lint_repo, preview_fixes, run_deep_dive, org_overview, explain_rule) para que clientes MCP possam consultar a saúde da CI; o servidor está listado no MCP Registry oficial e também pode ser executado a partir da imagem do container. As opções de instalação incluem uma extensão gh CLI, Homebrew, Scoop, uma imagem Docker multi-arch distroless, go install, aqua, mise/ubi, asdf, binários de release, pacotes deb/rpm/apk, complementos de shell e hooks de pre-commit. Um playground no navegador executa o linter e suas auto-correções client-side via WebAssembly. O README declara que o projeto é construído e mantido por um agente de IA e que a ferramenta apenas lê de repositórios; uso de repositórios privados precisa de permissões Actions read e Contents read.