convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
htekdev

Actions Debugger

htekdev/actions-debugger

Debugue erros do GitHub Actions com IA e base de conhecimento estruturada

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server com banco de dados de 65+ erros reais do GitHub Actions, consultável por agentes. Fornece diagnóstico automático de workflows, sugestões de correção e integração com Claude, Copilot CLI e Cursor. Disponível como CLI, MCP server ou skill do Copilot.

Instalação

$npx convez-ai htekdev/actions-debugger

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
v1.0.238
Issues abertas
13
Contribuidores
2

Casos de uso

  • Diagnóstico automático de falhas em workflows do GitHub Actions
  • Lookup rápido de erros CI/CD com padrões regex e soluções
  • Integração com assistentes de IA (Claude, Copilot) para debugging em tempo real

Veredito

Ferramenta sólida para quem trabalha com GitHub Actions. A base de dados estruturada de erros reais é útil, mas o valor real aparece integrado a um MCP client — standalone é mais uma referência que automação.

README

A tradução para o português deste README ainda está na fila.

@htekdev/actions-debugger

CI npm License: MIT

65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.

Stop debugging the same CI failures over and over. This repo packages 65+ real-world GitHub Actions error scenarios — with regex-matchable patterns, root causes, and copy-paste fixes — into formats that both humans and AI agents can consume.

What's Inside

errors/              → Structured YAML error database (65+ entries)
src/                 → CLI + MCP server (TypeScript)
.github/skills/      → Copilot CLI skills for CI debugging
.github/agents/      → Copilot agent definition

Quick Start

CLI (Zero Install)

# Look up an error
npx @htekdev/actions-debugger lookup "Permission to org/repo.git denied"

# Search by keyword
npx @htekdev/actions-debugger search "OIDC" --category permissions-auth

# Diagnose a workflow file
npx @htekdev/actions-debugger diagnose .github/workflows/ci.yml

# Get fix suggestions
npx @htekdev/actions-debugger suggest-fix "artifact upload fails intermittently"

# List all categories
npx @htekdev/actions-debugger categories

Output Formats

# Text (default for TTY)
npx @htekdev/actions-debugger lookup "error message"

# JSON (default when piped, or explicit)
npx @htekdev/actions-debugger lookup "error message" --format json

# Markdown
npx @htekdev/actions-debugger lookup "error message" --format md

Exit Codes

CodeMeaning
0Success / matches found
1No matches found
2Invalid input / parse error
3Database load error

As an MCP Server (Claude Desktop, Copilot CLI, Cursor, etc.)

npx @htekdev/actions-debugger

Add to your MCP client config:

{
  "mcpServers": {
    "actions-debugger": {
      "command": "npx",
      "args": ["@htekdev/actions-debugger"]
    }
  }
}

Client config locations:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
  • Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
  • VS Code (Copilot Chat): .vscode/mcp.json
  • Copilot CLI: .github/mcp.json (repo-level)
  • Windsurf: ~/.codeium/windsurf/mcp_config.json

As a Copilot CLI Skill (No MCP Required)

Copy .github/skills/actions-debugging-cli/SKILL.md to your repo's .github/skills/ directory. Any agent with shell access can use the CLI — no MCP config needed.

> **Skill reference:** For CI debugging, use the `actions-debugging-cli` skill.

Programmatic (npm Package)

import { loadErrorDatabase, lookupError, diagnoseWorkflow } from "@htekdev/actions-debugger";

const db = await loadErrorDatabase();

// Lookup by error message
const matches = lookupError(db, "Permission to org/repo.git denied");
console.log(matches[0].fix);

// Analyze a workflow
const issues = diagnoseWorkflow(db, workflowYamlString);

MCP Tools

ToolDescription
lookup_errorMatch an error message against 65+ known issues
diagnose_workflowStatic analysis of workflow YAML for common mistakes
suggest_fixContextual fix suggestions from error context
search_errorsFull-text search by keyword, category, severity
list_categoriesBrowse error categories with counts

Error Categories

CategoryDescription
yaml-syntaxYAML validation, key typos, expression errors
silent-failuresNo error shown, but wrong behavior
runner-environmentRunner issues, disk space, Docker, PATH
permissions-authGITHUB_TOKEN, OIDC, secrets, 403s
caching-artifactsCache misses, artifact v4 changes, corruption
triggersWorkflow not running, cron issues, dispatch
concurrency-timingJob cancellation, matrix, timeouts
known-unsolvedPlatform limitations with no fix

Contributing

See CONTRIBUTING.md for how to add new error entries. It's easy:

  1. Create a YAML file in the appropriate errors/{category}/ directory
  2. Follow the schema in errors/_schema.json
  3. Open a PR — CI validates your entry automatically

Source

All error scenarios sourced from: The Definitive GitHub Actions Debugging Guide

License

MIT — Hector Flores (htekdev)

Ver o original no GitHub

Bom para

Relacionados