@htekdev/actions-debugger 1.0.0

package/errors/runner-environment/disk-space.yml

@@ -0,0 +1,57 @@
+id: runner-environment-002
+title: "Runner Out of Disk Space"
+category: runner-environment
+severity: error
+tags:
+  - runner
+  - disk-space
+  - docker
+  - enospc
+  - ubuntu-latest
+patterns:
+  - regex: "No space left on device"
+    flags: "i"
+  - regex: "ENOSPC"
+    flags: "i"
+  - regex: "write .+ no space left on device"
+    flags: "i"
+error_messages:
+  - "No space left on device"
+  - "ENOSPC: no space left on device"
+root_cause: |
+  GitHub-hosted runners have finite disk space, and large Docker layers, Android SDKs,
+  toolchains, browser caches, or build artifacts can exhaust it mid-job. This frequently
+  shows up on `ubuntu-latest` when workflows build containers or multiple large targets.
+
+  The underlying job logic may be correct, but the runner image simply runs out of storage.
+fix: |
+  Free disk space early in the job, reduce artifact retention, and avoid downloading heavy
+  toolchains you do not need. If the workload is consistently too large, move the job to a
+  larger runner or split the build across jobs.
+fix_code:
+  - language: yaml
+    label: "Free disk space before heavy build steps"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: jlumbroso/free-disk-space@v1
+              with:
+                large-packages: true
+                docker-images: true
+                tool-cache: false
+            - run: docker build -t app .
+prevention:
+  - "Measure disk usage before and after large build steps with `df -h`."
+  - "Delete temporary artifacts and caches you do not need inside the job."
+  - "Avoid monolithic jobs that build every target on one runner."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners"
+  - url: "https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job"
+    label: "Choosing the runner for a job"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner disk space exhaustion"

package/errors/runner-environment/node-runtime-deprecation.yml

@@ -0,0 +1,56 @@
+id: runner-environment-009
+title: "Node.js Runtime Deprecation"
+category: runner-environment
+severity: warning
+tags:
+  - node
+  - runtime
+  - deprecation
+  - marketplace-actions
+  - compatibility
+patterns:
+  - regex: "Node\\.js 16 actions are deprecated"
+    flags: "i"
+  - regex: "Please update the following actions to use Node\\.js 20"
+    flags: "i"
+  - regex: "runs using Node 16 are deprecated"
+    flags: "i"
+error_messages:
+  - "Node.js 16 actions are deprecated."
+  - "Please update the following actions to use Node.js 20."
+root_cause: |
+  Some marketplace actions bundle a Node.js runtime. When GitHub deprecates an older
+  runtime such as Node 16, workflows can start emitting warnings or eventually fail if the
+  referenced action version has not been updated.
+
+  This is usually caused by pinning an old major version of an action long after the runner
+  platform has moved on.
+fix: |
+  Upgrade the affected action to a maintained version that uses the current supported Node
+  runtime. Review pinned SHAs and major versions for checkout, setup, artifact, and cache
+  actions first because they are common sources of these warnings.
+fix_code:
+  - language: yaml
+    label: "Upgrade action versions to Node 20-compatible releases"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 20
+        - uses: actions/upload-artifact@v4
+          with:
+            name: build-output
+            path: dist/
+prevention:
+  - "Review GitHub Actions deprecation notices and keep marketplace action versions current."
+  - "Prefer supported major versions from official `actions/*` repositories."
+  - "Audit pinned SHAs periodically so old runtimes do not linger unnoticed."
+docs:
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
+    label: "JavaScript action runtime metadata"
+  - url: "https://docs.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions"
+    label: "Metadata syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Node runtime deprecation warnings"

package/errors/silent-failures/github-token-no-trigger.yml

@@ -0,0 +1,57 @@
+id: silent-failures-002
+title: "GITHUB_TOKEN Cannot Trigger Downstream Workflows"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-token
+  - triggers
+  - downstream
+  - workflow-chain
+  - authentication
+patterns:
+  - regex: "events triggered by the GITHUB_TOKEN.*will not create a new workflow run"
+    flags: "i"
+  - regex: "github-actions\\[bot\\]"
+    flags: "i"
+  - regex: "GITHUB_TOKEN"
+    flags: "i"
+error_messages:
+  - "Events triggered by the GITHUB_TOKEN will not create a new workflow run."
+root_cause: |
+  Commits, tags, and releases created with the repository `GITHUB_TOKEN` are intentionally
+  prevented from triggering most downstream workflows. This is a platform safety feature to
+  stop accidental recursion and workflow loops.
+
+  The upstream workflow appears to succeed, but the dependent workflow never starts, which
+  makes this feel like a silent trigger failure.
+fix: |
+  Use a GitHub App installation token or a PAT when you intentionally need one workflow to
+  trigger another via `push`, `create`, or `release`. Keep `GITHUB_TOKEN` for normal repo
+  automation that should not fan out into new workflow runs.
+fix_code:
+  - language: yaml
+    label: "Use a non-GITHUB_TOKEN credential for recursive automation"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Create tag with a PAT
+              env:
+                GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+              run: |
+                git tag v${{ github.run_number }}
+                git push https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git --tags
+prevention:
+  - "Assume `GITHUB_TOKEN` will not fan out into downstream workflow runs unless you are using `workflow_dispatch` or `repository_dispatch`."
+  - "Document which automations require a GitHub App token or PAT."
+  - "Avoid recursive workflow designs that depend on implicit `push` triggers from `github-actions[bot]`."
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
+    label: "Automatic token authentication"
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows"
+    label: "Events that trigger workflows"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "GITHUB_TOKEN downstream trigger limitations"

package/errors/silent-failures/scheduled-workflow-disabled.yml

@@ -0,0 +1,59 @@
+id: silent-failures-001
+title: "Scheduled Workflows Silently Disabled After 60 Days"
+category: silent-failures
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - inactivity
+  - disabled
+  - automation
+patterns:
+  - regex: "This scheduled workflow is disabled because there hasn't been activity in this repository for at least 60 days"
+    flags: "i"
+  - regex: "schedule.*workflow.*disabled"
+    flags: "i"
+error_messages:
+  - "This scheduled workflow is disabled because there hasn't been activity in this repository for at least 60 days"
+root_cause: |
+  In public repositories, GitHub automatically disables scheduled workflows after about
+  60 days with no repository activity. Nothing in the workflow YAML is technically wrong,
+  but the cron job stops firing until someone re-enables it or new activity occurs.
+
+  This feels like a silent failure because the expected schedule disappears rather than
+  producing a normal failed run.
+fix: |
+  Re-enable the workflow in the Actions UI and keep the repository active. If the schedule
+  must stay alive in a low-activity repository, add a keepalive workflow that periodically
+  creates harmless activity.
+fix_code:
+  - language: yaml
+    label: "Keep scheduled workflows active"
+    code: |
+      name: Keepalive
+
+      on:
+        schedule:
+          - cron: '0 6 * * 1'
+        workflow_dispatch:
+
+      jobs:
+        keepalive:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: gautamkrishnar/keepalive-workflow@v2
+              with:
+                committer_username: github-actions[bot]
+                committer_email: 41898282+github-actions[bot]@users.noreply.github.com
+prevention:
+  - "Check the Actions tab periodically for disabled scheduled workflows in low-activity repositories."
+  - "Pair important cron automations with `workflow_dispatch` for manual recovery."
+  - "Use a keepalive strategy for public repos that rely on unattended schedules."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
+    label: "schedule event"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Disable and enable a workflow"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Scheduled workflows disabled after inactivity"

package/errors/triggers/cron-schedule-late.yml

@@ -0,0 +1,59 @@
+id: triggers-003
+title: "Cron Schedule Running Late or Not Running"
+category: triggers
+severity: warning
+tags:
+  - cron
+  - schedule
+  - delay
+  - forks
+  - best-effort
+patterns:
+  - regex: "schedule"
+    flags: "i"
+  - regex: "Delayed"
+    flags: "i"
+  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
+    flags: "i"
+error_messages:
+  - "Scheduled workflows can be delayed during periods of high loads of GitHub Actions workflow runs."
+root_cause: |
+  GitHub Actions cron is best-effort, not real-time scheduling. During peak usage windows,
+  scheduled workflows can start 15 to 45 minutes late. In forks, scheduled workflows are also
+  disabled by default, so a copied workflow may never run until someone explicitly enables it.
+
+  The YAML can be correct and the repository can still see timing drift because the platform
+  does not guarantee precise minute-by-minute execution.
+fix: |
+  Treat cron timing as approximate. Schedule important automations away from the top of the
+  hour, add tolerance for startup drift, and provide a `workflow_dispatch` fallback for jobs
+  that sometimes need manual recovery.
+fix_code:
+  - language: yaml
+    label: "Add jitter-friendly scheduling and manual fallback"
+    code: |
+      name: Nightly maintenance
+
+      on:
+        schedule:
+          - cron: '17 3 * * *'
+        workflow_dispatch:
+
+      jobs:
+        maintain:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/maintenance.sh
+prevention:
+  - "Avoid scheduling critical jobs exactly at minute 0 because that is a common contention window."
+  - "Use external monitoring if a schedule must be near-real-time."
+  - "Enable scheduled workflows manually after creating a fork or after long inactivity."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
+    label: "schedule event"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Disable and enable a workflow"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Cron schedules running late"

package/errors/triggers/workflow-not-triggering.yml

@@ -0,0 +1,60 @@
+id: triggers-001
+title: "Workflow Not Triggering At All"
+category: triggers
+severity: error
+tags:
+  - triggers
+  - workflow-file
+  - default-branch
+  - on
+  - events
+patterns:
+  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
+    flags: "i"
+  - regex: "Workflow file .* not found on the default branch"
+    flags: "i"
+  - regex: "No runs found for this workflow"
+    flags: "i"
+error_messages:
+  - "This event will only trigger a workflow run if the workflow file exists on the default branch"
+root_cause: |
+  Some events only trigger if the workflow file itself exists on the repository's default
+  branch. A workflow can look perfectly valid in a feature branch, but GitHub will ignore it
+  for certain event types until the file is present on the default branch with correct `on:`
+  syntax and placement under `.github/workflows/`.
+
+  A wrong indentation level under `on:`, a typo in the event name, or putting the file in the
+  wrong directory can create the same symptom: nothing runs.
+fix: |
+  Confirm the workflow file lives in `.github/workflows/`, validate the `on:` block, and make
+  sure the workflow file already exists on the default branch for the event you expect to fire.
+fix_code:
+  - language: yaml
+    label: "Use valid workflow location and trigger syntax"
+    code: |
+      name: CI
+
+      on:
+        push:
+          branches:
+            - main
+        pull_request:
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Keep workflow files only under `.github/workflows/`."
+  - "Merge new workflow files to the default branch before relying on events like `schedule` or `workflow_dispatch`."
+  - "Validate event names and indentation in every `on:` block."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows"
+    label: "Events that trigger workflows"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Workflow not triggering"

package/errors/yaml-syntax/if-always-true.yml

@@ -0,0 +1,52 @@
+id: yaml-syntax-007
+title: "if: Conditionals Always Evaluating to true"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - if
+  - expressions
+  - conditionals
+  - yaml
+  - truthy
+patterns:
+  - regex: "Evaluating condition for step: .*"
+    flags: "i"
+  - regex: "Expanded: '.+\\n.+" 
+    flags: "i"
+  - regex: "Result: true"
+    flags: "i"
+error_messages:
+  - "Result: true"
+root_cause: |
+  Using a block scalar such as `if: |` turns the condition into a multi-line string.
+  In GitHub Actions expressions, any non-empty string is truthy, so the step or job can
+  run even when the intended logical check should have been false.
+
+  A similar footgun happens when the expression is written with extra trailing text or
+  whitespace outside the `${{ }}` block, which changes the value from a boolean expression
+  into a plain string.
+fix: |
+  Keep `if:` expressions on a single line and avoid YAML pipe scalars for conditionals.
+  Make sure the entire value is the expression itself, with no extra text after `${{ }}`.
+fix_code:
+  - language: yaml
+    label: "Write if as a single-line expression"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Never use `if: |` for GitHub Actions conditionals."
+  - "Turn on step debug logging when a condition seems inverted and inspect the `Expanded:` and `Result:` lines."
+  - "Keep boolean logic entirely inside a single `${{ }}` expression."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif"
+    label: "jobs.<job_id>.if"
+  - url: "https://docs.github.com/en/actions/learn-github-actions/expressions"
+    label: "Expressions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "if expressions that always evaluate true"

package/errors/yaml-syntax/secrets-in-if.yml

@@ -0,0 +1,55 @@
+id: yaml-syntax-005
+title: "secrets.* in if: Conditions — Silent Failures"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - secrets
+  - if
+  - expressions
+  - contexts
+  - env
+patterns:
+  - regex: "Unrecognized named-value: 'secrets'"
+    flags: "i"
+  - regex: "The workflow is not valid\\..*named-value: 'secrets'"
+    flags: "i"
+  - regex: "Context access might be invalid: secrets\\."
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'secrets'"
+root_cause: |
+  The `secrets` context is not available everywhere an expression can appear, and using
+  `secrets.*` directly inside an `if:` condition is a common trap. Depending on where the
+  expression is evaluated, GitHub Actions can reject the workflow or effectively treat the
+  check as unavailable.
+
+  The safe pattern is to map the secret into an environment variable first, then evaluate
+  the environment variable in the `if:` expression.
+fix: |
+  Pass the secret through `env:` and reference `env.NAME` in the `if:`. This keeps the
+  conditional supported and avoids direct `secrets.*` access in the condition.
+fix_code:
+  - language: yaml
+    label: "Gate a step using env instead of secrets directly"
+    code: |
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          env:
+            HAS_TOKEN: ${{ secrets.NPM_TOKEN }}
+          steps:
+            - name: Publish
+              if: ${{ env.HAS_TOKEN != '' }}
+              run: npm publish
+prevention:
+  - "Do not reference `secrets.*` directly in `if:` unless the docs explicitly allow that context."
+  - "Promote secrets into `env` when a step should be conditionally gated."
+  - "Check the contexts reference before using a context in expressions."
+docs:
+  - url: "https://docs.github.com/en/actions/learn-github-actions/contexts"
+    label: "Contexts"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
+    label: "jobs.<job_id>.steps[*].if"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Secrets in if conditions"

package/errors/yaml-syntax/unexpected-yaml-key.yml

@@ -0,0 +1,69 @@
+id: yaml-syntax-001
+title: "Unexpected or Typo'd YAML Keys"
+category: yaml-syntax
+severity: error
+tags:
+  - yaml
+  - syntax
+  - validation
+  - keys
+  - typos
+patterns:
+  - regex: "Unexpected value '\\w+'"
+    flags: "i"
+  - regex: "unexpected key \"\\w+\" for step"
+    flags: "i"
+  - regex: "The workflow is not valid\\..*Unexpected value '\\w+'"
+    flags: "i"
+error_messages:
+  - "Unexpected value 'default'"
+  - "Unexpected value 'Shell'"
+  - "Unexpected value 'branch'"
+root_cause: |
+  GitHub Actions workflow keys are schema-validated and case-sensitive. A typo like
+  `default:` instead of `defaults:`, `Shell:` instead of `shell:`, or `branch:` instead
+  of `branches:` is treated as an unknown key and the workflow is rejected before it runs.
+
+  This usually happens when copying snippets from memory or mixing YAML conventions from
+  other tools into GitHub Actions syntax.
+fix: |
+  Replace the invalid key with the exact schema-supported key name. Double-check plural
+  forms and casing against the workflow syntax reference.
+
+  Common fixes:
+  - `default:` -> `defaults:`
+  - `Shell:` -> `shell:`
+  - `branch:` -> `branches:`
+fix_code:
+  - language: yaml
+    label: "Use valid GitHub Actions keys"
+    code: |
+      name: CI
+
+      on:
+        push:
+          branches:
+            - main
+
+      defaults:
+        run:
+          shell: bash
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Validate workflow files against the GitHub Actions workflow syntax docs before committing."
+  - "Prefer editing from working examples instead of typing keys from memory."
+  - "Use code review checks for `defaults`, `shell`, and `branches` because those typos are common."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+  - url: "https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions"
+    label: "Understanding GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "YAML validation and typo'd keys"

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@htekdev/actions-debugger",
+  "version": "1.0.0",
+  "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "actions-debugger": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "errors",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "validate-errors": "node --import tsx scripts/validate-errors.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "github-actions",
+    "debugging",
+    "mcp",
+    "model-context-protocol",
+    "copilot",
+    "ci-cd",
+    "error-database"
+  ],
+  "author": "Hector Flores <hector.flores@htek.dev> (https://htek.dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/htekdev/actions-debugger.git"
+  },
+  "homepage": "https://htek.dev/articles/github-actions-debugging-guide",
+  "bugs": {
+    "url": "https://github.com/htekdev/actions-debugger/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "glob": "^11.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}