| name | actions-debugging |
| description | GitHub Actions error lookup — match error messages against a database of 65+ known issues with root causes and fixes. Use when agent sees "Actions error", "CI failed", "workflow broken", "debug Actions", "why did my build fail", "GitHub Actions help", or any CI/CD debugging activity.
|
Actions Debugging Skill
Purpose
Match GitHub Actions error messages against a curated database of 65+ known errors.
Every entry includes the error pattern, root cause, and copy-paste fix.
When to Use
- Agent encounters a GitHub Actions error message in logs
- User asks for help debugging a CI/CD failure
- Workflow analysis reveals potential issues
Error Categories
- 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
Lookup Procedure
- Extract the error message from the CI logs
- Search the error database (MCP
lookup_error if available, or pattern match against known errors)
- If match found: return root cause + fix + prevention steps + doc links
- If no match: suggest enabling debug logging and checking the Essential Tooling section
Quick Reference — Top 10 Most Common
| # | Error Pattern | Category | Fix Summary |
|---|
| 1 | Permission to org/repo.git denied | permissions-auth | Add permissions: contents: write |
| 2 | Cache not found for input keys | caching-artifacts | Check branch scoping, rate limits |
| 3 | Unexpected value 'X' | yaml-syntax | Fix key casing (default: → defaults:) |
| 4 | No space left on device | runner-environment | Add jlumbroso/free-disk-space |
| 5 | Workflow never appears in Actions tab | triggers | Check file is on default branch |
| 6 | set-output command is deprecated | runner-environment | Use >> $GITHUB_OUTPUT |
| 7 | Node.js 16 actions are deprecated | runner-environment | Bump action versions |
| 8 | Step if: always evaluates to true | yaml-syntax | Remove pipe scalar / trailing spaces |
| 9 | Scheduled workflow stops after 60 days | silent-failures | Add keepalive-workflow action |
| 10 | GITHUB_TOKEN commit doesn't trigger | silent-failures | Use GitHub App token or PAT |
MCP Server
If the actions-debugger MCP server is available, use these tools for programmatic lookup:
lookup_error(error_message) — Match against known patternsdiagnose_workflow(workflow_yaml) — Static analysissuggest_fix(error_context) — Contextual suggestionssearch_errors(query) — Full-text searchlist_categories() — Browse categories
Source
Full reference: https://htek.dev/articles/github-actions-debugging-guide
