@htekdev/actions-debugger 1.0.22 → 1.0.23

package/errors/known-unsolved/reusable-secrets-inherit-not-deep-forwarded.yml

@@ -0,0 +1,113 @@
+id: known-unsolved-021
+title: "secrets: inherit Does Not Cascade to Second-Level Nested Reusable Workflows"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - secrets
+  - secrets-inherit
+  - nesting
+  - silent-failure
+
+patterns:
+  - regex: "secret .+ is required, but not provided"
+    flags: "i"
+  - regex: "secrets\\.\\w+ is not a valid secret key"
+    flags: "i"
+
+error_messages:
+  - "Secret GIT_PAT is required, but not provided"
+  - "Required secret 'MY_SECRET' was not provided by the caller"
+
+root_cause: |
+  `secrets: inherit` in a caller workflow passes ALL repository and organization
+  secrets to the directly-called (first-level) reusable workflow. However, if that
+  reusable workflow then calls ANOTHER reusable workflow (second level), those
+  inherited secrets are NOT automatically forwarded to the second level.
+
+  Each `workflow_call` boundary is a discrete secrets scope. `secrets: inherit`
+  only covers one hop. If you have:
+
+    root.yml  →  (secrets: inherit)  →  level1.yml  →  level2.yml
+
+  then `level2.yml` receives an empty secrets context unless `level1.yml`
+  explicitly passes them via its own `secrets:` block.
+
+  This is a platform design decision, not a bug. GitHub has confirmed that
+  `secrets: inherit` does not cascade through multiple `workflow_call` layers.
+  There is no current mechanism for automatic multi-level secret propagation.
+
+  Community reports: actions/runner#2709 (open, labeled bug, 8 👍, 2023–2025),
+  community/discussions/23107.
+
+fix: |
+  Explicitly declare and pass secrets at EVERY reusable workflow boundary.
+
+  For level1.yml to forward secrets to level2.yml, level1.yml must:
+    1. Declare secrets in its on.workflow_call.secrets block.
+    2. Pass those secrets explicitly in the jobs.*.secrets block when calling level2.yml.
+
+  Alternatively, use `secrets: inherit` at EACH level — but the calling workflow
+  (level1.yml) itself must also explicitly declare the secrets it expects so
+  they are available in its scope to pass down.
+
+fix_code:
+  - language: yaml
+    label: "root.yml — caller uses secrets: inherit for first hop"
+    code: |
+      jobs:
+        call-level1:
+          uses: ./.github/workflows/level1.yml
+          secrets: inherit   # passes ALL secrets to level1.yml only
+
+  - language: yaml
+    label: "level1.yml — must declare AND re-forward secrets to level2.yml"
+    code: |
+      on:
+        workflow_call:
+          secrets:
+            MY_SECRET:
+              required: true
+            DEPLOY_TOKEN:
+              required: false
+
+      jobs:
+        call-level2:
+          uses: ./.github/workflows/level2.yml
+          secrets:
+            MY_SECRET: ${{ secrets.MY_SECRET }}       # explicit re-forward
+            DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} # explicit re-forward
+
+  - language: yaml
+    label: "level2.yml — must declare secrets it expects"
+    code: |
+      on:
+        workflow_call:
+          secrets:
+            MY_SECRET:
+              required: true
+            DEPLOY_TOKEN:
+              required: false
+
+      jobs:
+        use-secrets:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use secret
+              run: echo "token length = ${#MY_SECRET}"
+              env:
+                MY_SECRET: ${{ secrets.MY_SECRET }}
+
+prevention:
+  - "Audit every workflow_call boundary in nested reusable workflows — each hop must explicitly forward secrets."
+  - "Document required secrets at every level in workflow comments to avoid silent empty-string failures."
+  - "Use composite actions instead of nested reusable workflows when secrets do not need to cross job boundaries — composite actions share the parent job's secrets context automatically."
+  - "Test nested workflows by echoing a non-sensitive derived value (e.g., secret length) at each level to confirm propagation."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/reusing-workflows#passing-secrets-to-nested-workflows"
+    label: "GitHub Docs — Passing secrets to nested workflows"
+  - url: "https://github.com/actions/runner/issues/2709"
+    label: "actions/runner#2709 — Passing secrets to reusable workflow does not work (open, 2023)"
+  - url: "https://github.com/orgs/community/discussions/23107"
+    label: "community/discussions#23107 — Inheriting secrets in reusable workflows"

package/errors/runner-environment/org-runner-group-dispatch-null.yml

@@ -0,0 +1,102 @@
+id: runner-environment-059
+title: "Org-Level Self-Hosted Runner in Group Never Dispatched — Job Queued Indefinitely"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted-runner
+  - runner-group
+  - org-runner
+  - queued
+  - dispatch
+
+patterns:
+  - regex: "no runner.*matching.*label.*self-hosted"
+    flags: "i"
+  - regex: "runner_group_id.*null"
+    flags: "i"
+
+error_messages:
+  - "Can't find any online and idle self-hosted runner in the current repository, account/organization that matches the required labels: 'self-hosted, <group-name>'"
+  - "Waiting for a runner to pick up this job..."
+
+root_cause: |
+  When a self-hosted runner is registered at the ORGANIZATION level and placed into
+  a runner group that has explicit repository access, the GitHub Actions dispatcher
+  sometimes fails to resolve the runner's group membership within the target
+  repository's scope. The job's metadata shows runner_group_id: null throughout the
+  entire wait period, meaning the internal broker never matched the org-level runner
+  to the queued job.
+
+  This affects runners using the V2 broker protocol
+  (broker.actions.githubusercontent.com) on GitHub Team and Enterprise plans.
+  The runner appears "Online" in the org settings, the runner group lists the target
+  repository as allowed, and the runs-on labels match — yet the job never starts.
+
+  Root technical cause: the dispatcher resolves runner group membership differently
+  for org-scoped runners vs. repo-scoped runners. When the runner is registered at
+  org scope, the broker does not propagate its group_id to the queued job record,
+  so no assignment occurs.
+
+fix: |
+  Short-term workaround (immediate):
+    Re-register the runner at the REPOSITORY level instead of the organization level.
+    This bypasses the group dispatch path and the job is assigned immediately.
+
+  Long-term fix:
+    1. Monitor GitHub Actions runner releases for a fix to org-level group dispatch.
+    2. Use GitHub-hosted larger runners or runner scale sets (Actions Runner Controller)
+       for org-level sharing — these use a different dispatch mechanism that is not
+       affected by this bug.
+    3. If org-level management is required, use runner groups with repo-scoped runner
+       registration and rely on group access policies to control visibility.
+
+fix_code:
+  - language: yaml
+    label: "Re-register runner at repository level (workaround)"
+    code: |
+      # 1. Remove the runner from the org-level runner list in GitHub UI:
+      #    Settings → Actions → Runners → (select runner) → Remove runner
+      #
+      # 2. Re-register the runner at the REPO level:
+      #    <repo> → Settings → Actions → Runners → New self-hosted runner
+      #    Follow setup commands shown in the UI.
+      #
+      # 3. Your workflow runs-on stays the same:
+      jobs:
+        build:
+          runs-on: [self-hosted, my-runner-label]
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: "Use Actions Runner Controller (ARC) for org-level runners"
+    code: |
+      # ARC scale sets are not affected by the org-runner group dispatch bug.
+      # Install the controller chart and create a runner scale set:
+      #
+      # helm install arc-runner-set \
+      #   --namespace arc-runners \
+      #   oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
+      #   --set githubConfigUrl=https://github.com/<org> \
+      #   --set githubConfigSecret.github_token=<token>
+      #
+      # Then reference in your workflow:
+      jobs:
+        build:
+          runs-on: arc-runner-set
+          steps:
+            - uses: actions/checkout@v4
+
+prevention:
+  - "Register self-hosted runners at repository level when possible to avoid org-level dispatch issues."
+  - "After registering a runner, trigger a test workflow immediately to confirm dispatch before relying on it in production."
+  - "Use Actions Runner Controller (ARC) scale sets for org-wide shared runners — ARC bypasses the runner group dispatch path."
+  - "Check runner_group_id via the API (`GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs`) when a job is stuck — null means dispatch failed at the broker level."
+
+docs:
+  - url: "https://github.com/actions/runner/issues/4429"
+    label: "actions/runner#4429 — Org-level runner never dispatched despite correct group access (May 2026)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs — Runner registration scopes"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow"
+    label: "GitHub Docs — Using self-hosted runners in a workflow"

package/errors/triggers/workflow-run-checkout-uses-default-branch.yml

@@ -0,0 +1,114 @@
+id: triggers-019
+title: "workflow_run-Triggered Job Checks Out Default Branch, Not the Triggering PR's Branch"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - checkout
+  - default-branch
+  - silent-failure
+  - pull-request
+
+patterns:
+  - regex: "workflow_run.*head_branch"
+    flags: "i"
+  - regex: "github\\.event\\.workflow_run\\.head_branch"
+    flags: "i"
+
+error_messages:
+  - "# No error message — the job silently runs against the wrong branch (e.g., main instead of the PR's feature branch)"
+  - "HEAD is now at <main-branch-commit> — expected feature branch content not present"
+
+root_cause: |
+  When a workflow is triggered via `workflow_run`, the triggered workflow ALWAYS
+  runs in the context of the repository's DEFAULT branch, not the branch that
+  caused the original workflow to run.
+
+  This means that `actions/checkout` without an explicit `ref:` will check out
+  the default branch (e.g., `main`), even when the triggering workflow ran on a
+  feature branch or PR. The job may silently pass because it's testing old code
+  on `main` rather than the developer's new changes.
+
+  This is by design: `workflow_run` is intended for privileged workflows that
+  run in the base repository context regardless of where the triggering push came
+  from. It avoids giving fork PRs access to secrets — but it also means the
+  checkout behavior surprises developers expecting to test branch code.
+
+  The branch of the triggering workflow IS available via the event context:
+    `github.event.workflow_run.head_branch`
+    `github.event.workflow_run.head_sha`
+
+fix: |
+  Explicitly set the `ref:` in your `actions/checkout` step to the triggering
+  workflow's head commit SHA or branch name.
+
+  Use `head_sha` (not `head_branch`) for more precise pinning — branch names
+  can advance between trigger and checkout for busy repositories.
+
+fix_code:
+  - language: yaml
+    label: "Checkout the triggering workflow's exact commit"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI — Unit Tests"]
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Use head_sha for precise pinning — not head_branch
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+  - language: yaml
+    label: "Download artifacts from the triggering workflow run instead of re-checking out"
+    code: |
+      # For deployment workflows, prefer downloading the build artifact
+      # from the triggering run rather than re-building from source.
+      # This avoids the branch checkout problem entirely.
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                run-id: ${{ github.event.workflow_run.id }}
+                name: build-output
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Deploy
+              run: ./deploy.sh
+
+  - language: yaml
+    label: "Guard against running on wrong branch with a condition"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Only deploy when triggered from the main branch to avoid
+          # accidentally deploying non-main code
+          if: |
+            github.event.workflow_run.conclusion == 'success' &&
+            github.event.workflow_run.head_branch == 'main'
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+prevention:
+  - "Always specify ref: ${{ github.event.workflow_run.head_sha }} in checkout steps inside workflow_run-triggered jobs."
+  - "Prefer downloading build artifacts over re-checking-out source code in workflow_run jobs to avoid branch confusion."
+  - "Log github.event.workflow_run.head_branch and head_sha at the start of workflow_run jobs for debugging."
+  - "Use the conclusion check (if: github.event.workflow_run.conclusion == 'success') to avoid deploying failed builds."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs — workflow_run event"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#using-data-from-the-triggering-workflow"
+    label: "GitHub Docs — Using data from the triggering workflow"
+  - url: "https://stackoverflow.com/questions/76184351"
+    label: "SO#76184351 — workflow_run job runs on wrong (default) branch"

package/errors/yaml-syntax/reusable-workflow-nesting-depth-exceeded.yml

@@ -0,0 +1,113 @@
+id: yaml-syntax-024
+title: "Reusable Workflow Nesting Exceeds Maximum Depth of 4 Levels"
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflow
+  - nesting
+  - depth-limit
+  - workflow_call
+  - yaml-parse-error
+
+patterns:
+  - regex: "would exceed the limit on called workflow depth of \\d+"
+    flags: "i"
+  - regex: "calls workflow .+, but doing so would exceed the limit"
+    flags: "i"
+
+error_messages:
+  - "error parsing called workflow \"./.github/workflows/deploy.yml@\": job \"build\" calls workflow \"./.github/workflows/release.yml@\", but doing so would exceed the limit on called workflow depth of 3"
+  - "but doing so would exceed the limit on called workflow depth of 3"
+
+root_cause: |
+  GitHub Actions enforces a maximum reusable workflow call depth of 4 levels total.
+  The top-level workflow counts as level 1, so the maximum number of sequential
+  workflow_call hops is 3 (levels 2, 3, and 4).
+
+  The error message says "depth of 3" because it refers to the maximum allowed
+  zero-indexed depth of called workflows, not the total chain length.  When your
+  chain would require a 4th call (fifth total workflow), GitHub rejects the YAML
+  at parse time — before any runner picks up the job.
+
+  Example chain that fails:
+    root.yml → a.yml → b.yml → c.yml → d.yml   (depth index 4 → rejected)
+
+  Example chain that succeeds:
+    root.yml → a.yml → b.yml → c.yml            (depth index 3 → allowed)
+
+  This limit was increased from 2 to 3 in August 2022 and is currently fixed at 4
+  total levels (depth index 0–3).
+
+fix: |
+  Reduce the nesting depth so the total chain is 4 levels or fewer.
+  Strategies:
+
+  1. Flatten: merge two deeply-nested reusable workflows into one.
+  2. Convert inner reusables to composite actions — composite actions do NOT
+     count toward the reusable workflow depth limit.
+  3. Restructure so leaf workflows are composite actions, keeping reusable
+     workflows only at the top layers.
+
+fix_code:
+  - language: yaml
+    label: "Replace inner reusable workflow with a composite action"
+    code: |
+      # Instead of calling another reusable workflow at depth 4,
+      # use a composite action in .github/actions/my-task/action.yml
+      # which has no depth limit.
+
+      # .github/actions/my-task/action.yml
+      name: My Task
+      description: Previously a reusable workflow, now a composite action
+      runs:
+        using: composite
+        steps:
+          - name: Do the work
+            shell: bash
+            run: echo "doing the work"
+
+      # Called from the deeply-nested workflow:
+      - name: Run my task
+        uses: ./.github/actions/my-task  # composite, no depth counted
+
+  - language: yaml
+    label: "Flatten two reusable workflows into one to reduce depth"
+    code: |
+      # Before (depth 4 — fails):
+      # root.yml  →  build.yml  →  test.yml  →  lint.yml  →  scan.yml
+      #
+      # After (depth 3 — passes):
+      # Merge lint.yml and scan.yml into a single quality.yml
+
+      # quality.yml
+      on:
+        workflow_call:
+          inputs:
+            target:
+              required: true
+              type: string
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "linting ${{ inputs.target }}"
+        scan:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "scanning ${{ inputs.target }}"
+
+prevention:
+  - "Map your reusable workflow call chain before writing YAML — count total levels."
+  - "Prefer composite actions for leaf-level tasks; they have no depth limit."
+  - "Limit reusable workflow use to high-value shared orchestration layers, not every step."
+  - "If depth 4 is genuinely required, consider splitting the pipeline into separate triggered workflows using workflow_run instead of nested workflow_call."
+
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/reusing-workflows#nesting-reusable-workflows"
+    label: "GitHub Docs — Nesting reusable workflows"
+  - url: "https://github.blog/changelog/2022-08-22-github-actions-improvements-to-reusable-workflows-2/"
+    label: "GitHub Changelog — Nesting increased to 4 levels (August 2022)"
+  - url: "https://github.com/actions/runner/issues/1797"
+    label: "actions/runner#1797 — Original depth-limit enhancement request"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",