Actions Debugger
htekdev/actions-debugger
Debugue erros do GitHub Actions com IA e base de conhecimento estruturada
Ver no GitHubMCP 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-debugger1 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
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
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
| Code | Meaning |
|---|---|
| 0 | Success / matches found |
| 1 | No matches found |
| 2 | Invalid input / parse error |
| 3 | Database 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
| Tool | Description |
|---|---|
lookup_error | Match an error message against 65+ known issues |
diagnose_workflow | Static analysis of workflow YAML for common mistakes |
suggest_fix | Contextual fix suggestions from error context |
search_errors | Full-text search by keyword, category, severity |
list_categories | Browse error categories with counts |
Error Categories
| Category | Description |
|---|---|
yaml-syntax | YAML validation, key typos, expression errors |
silent-failures | No error shown, but wrong behavior |
runner-environment | Runner issues, disk space, Docker, PATH |
permissions-auth | GITHUB_TOKEN, OIDC, secrets, 403s |
caching-artifacts | Cache misses, artifact v4 changes, corruption |
triggers | Workflow not running, cron issues, dispatch |
concurrency-timing | Job cancellation, matrix, timeouts |
known-unsolved | Platform limitations with no fix |
Contributing
See CONTRIBUTING.md for how to add new error entries. It's easy:
- Create a YAML file in the appropriate
errors/{category}/directory - Follow the schema in
errors/_schema.json - 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)