@htekdev/actions-debugger 1.0.66 → 1.0.67

package/errors/known-unsolved/self-hosted-runner-stuck-queued-no-timeout.yml

@@ -0,0 +1,73 @@
+id: known-unsolved-042
+title: 'Job queues indefinitely when no self-hosted runner matches labels — no automatic queue-wait timeout'
+category: known-unsolved
+severity: limitation
+tags:
+  - self-hosted
+  - queued
+  - runner-labels
+  - timeout
+  - stuck-job
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+  - regex: 'Job is waiting for a hosted runner to come online'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a runner to pick up this job'
+  - 'Job is waiting for a hosted runner to come online'
+root_cause: |
+  When a job specifies runs-on: self-hosted (or a label array containing self-hosted),
+  GitHub places the job in a queue and waits for a matching runner to become available.
+  If no registered runner matches all required labels — because the runner is offline,
+  deregistered, at capacity, or the labels are mistyped — the job remains in "Queued"
+  state indefinitely with the message "Waiting for a runner to pick up this job."
+
+  GitHub does not apply an automatic queue-wait timeout. The only enforced limit is the
+  overall workflow timeout-minutes (default 360 minutes, maximum 35 days for self-hosted
+  runners). Runner labels are matched case-sensitively, so [self-hosted, Linux] does not
+  match a runner registered as [self-hosted, linux].
+
+  This is a recurring GitHub Community request: developers frequently discover queued jobs
+  hours or days later after expecting fast CI feedback.
+fix: |
+  There is no GitHub-native queue-wait timeout distinct from job runtime. Mitigations:
+  1. Add timeout-minutes at the job level to cap total job time including queue wait
+  2. Verify runner label spellings exactly match labels registered on the runner
+     (Settings → Actions → Runners shows registered labels)
+  3. Ensure at least one runner with all required labels is online and idle
+  4. Use ephemeral (JIT) runners with auto-scaling to prevent capacity exhaustion
+fix_code:
+  - language: yaml
+    label: 'Add timeout-minutes to fail fast when no runner is available'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          timeout-minutes: 30    # job fails if no runner picks it up within 30 minutes
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: 'Fallback to GitHub-hosted runner when self-hosted is unavailable'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ vars.USE_SELF_HOSTED == 'true' && fromJSON('["self-hosted","linux","x64"]') || 'ubuntu-latest' }}
+          timeout-minutes: 60
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - 'Always set timeout-minutes on self-hosted runner jobs to prevent indefinite queuing'
+  - 'Verify runner labels match exactly — labels are case-sensitive (Linux vs linux)'
+  - 'Monitor runner pool health at Settings → Actions → Runners and alert on all-offline conditions'
+  - 'Use ephemeral (JIT) runners with auto-scaling to ensure available capacity on demand'
+  - 'Consider GitHub-hosted runner fallback for critical workflows'
+docs:
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-labels'
+    label: 'Self-hosted runner labels — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'jobs.<job>.timeout-minutes — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'Autoscaling with self-hosted runners — GitHub Docs'

package/errors/silent-failures/actions-runner-debug-must-be-secret-not-variable.yml

@@ -0,0 +1,62 @@
+id: silent-failures-066
+title: 'ACTIONS_RUNNER_DEBUG and ACTIONS_STEP_DEBUG must be repository secrets, not variables'
+category: silent-failures
+severity: silent-failure
+tags:
+  - debug-logging
+  - ACTIONS_RUNNER_DEBUG
+  - ACTIONS_STEP_DEBUG
+  - secrets
+  - variables
+  - troubleshooting
+patterns:
+  - regex: 'ACTIONS_RUNNER_DEBUG|ACTIONS_STEP_DEBUG'
+    flags: 'i'
+error_messages:
+  - 'No additional debug output despite ACTIONS_RUNNER_DEBUG=true'
+  - 'Debug logging not enabled even though variable is set to true'
+root_cause: |
+  GitHub Actions checks ACTIONS_RUNNER_DEBUG and ACTIONS_STEP_DEBUG only when they are
+  set as repository or organization secrets. Setting them as repository variables
+  (Settings → Secrets and variables → Actions → Variables tab) has no effect whatsoever.
+  The runner bootstrap reads debug flags from the secrets store before variable contexts
+  are available, so a vars.ACTIONS_RUNNER_DEBUG reference inside the workflow YAML is
+  also ineffective. No warning is emitted when the variable exists but the corresponding
+  secret does not — the runner simply operates in non-debug mode silently.
+fix: |
+  Set ACTIONS_RUNNER_DEBUG and/or ACTIONS_STEP_DEBUG as repository secrets (not variables)
+  with the value "true":
+
+    Settings → Secrets and variables → Actions → Secrets tab → New repository secret
+      Name:  ACTIONS_RUNNER_DEBUG
+      Value: true
+
+  Alternatively, use the "Re-run jobs" UI button and check "Enable debug logging" for a
+  one-time debug run without creating a permanent secret.
+fix_code:
+  - language: yaml
+    label: 'Debug flags require repository secrets — no workflow YAML change needed'
+    code: |
+      # Create these as repository SECRETS (not Variables):
+      #   ACTIONS_RUNNER_DEBUG = true   (verbose runner diagnostic logs)
+      #   ACTIONS_STEP_DEBUG   = true   (verbose step-level output including set-output calls)
+      #
+      # Setting them under the Variables tab has NO effect.
+      # For one-off debugging use "Re-run jobs" → check "Enable debug logging".
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner debug active when ACTIONS_RUNNER_DEBUG secret = true"
+prevention:
+  - 'Set ACTIONS_RUNNER_DEBUG and ACTIONS_STEP_DEBUG as Secrets, not Variables'
+  - 'Use the Re-run with debug logging checkbox for temporary one-off debugging'
+  - 'Check the Secrets tab — not the Variables tab — under Settings → Secrets and variables → Actions'
+  - 'Remember: debug flags are read during runner bootstrap before the vars context is available'
+docs:
+  - url: 'https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging'
+    label: 'Enabling debug logging — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions'
+    label: 'Using secrets in GitHub Actions — GitHub Docs'

package/errors/silent-failures/working-directory-ignored-on-uses-steps.yml

@@ -0,0 +1,80 @@
+id: silent-failures-067
+title: 'working-directory on a uses: step is silently ignored — only applies to run: steps'
+category: silent-failures
+severity: silent-failure
+tags:
+  - working-directory
+  - uses
+  - composite-action
+  - run
+  - path
+  - configuration
+patterns:
+  - regex: 'Error.*ENOENT.*no such file or directory'
+    flags: 'i'
+  - regex: 'No such file or directory'
+    flags: 'i'
+error_messages:
+  - 'Action runs from workspace root instead of specified working-directory'
+  - 'ENOENT: no such file or directory — action ignoring working-directory set on uses: step'
+root_cause: |
+  The step-level working-directory property only affects run: steps that execute shell
+  commands. Steps that use the uses: keyword to invoke an action — whether a JavaScript
+  action, Docker action, or composite action — silently ignore working-directory. The
+  property is discarded with no warning logged. The action runs from GITHUB_WORKSPACE
+  (the repository root) or from the action's own directory, not the directory specified
+  on the step.
+
+  This is a documented GitHub Actions limitation that surprises many developers who expect
+  working-directory to behave like a cd command applied to the entire step, regardless of
+  step type. It is one of the most common "action runs in wrong directory" reports on GitHub
+  Community Discussions.
+fix: |
+  Pass the desired directory as an explicit input to the action. For run: steps in the same
+  job, use defaults.run.working-directory at the job level. Do not set working-directory on
+  uses: steps — it is silently discarded.
+fix_code:
+  - language: yaml
+    label: 'Use job-level defaults.run for run steps; pass input for uses steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          defaults:
+            run:
+              working-directory: ./packages/my-app   # applies to all run: steps only
+
+          steps:
+            - uses: actions/checkout@v4
+
+            - run: npm install      # runs in ./packages/my-app ✓
+
+            # For uses: steps, pass the directory as an explicit action input:
+            - uses: ./.github/actions/my-action
+              with:
+                working-directory: ./packages/my-app   # action must accept this input
+  - language: yaml
+    label: 'Composite action: declare working-directory as an input'
+    code: |
+      # In .github/actions/my-action/action.yml:
+      inputs:
+        working-directory:
+          description: 'Directory to run in'
+          default: '.'
+      runs:
+        using: composite
+        steps:
+          - run: npm test
+            shell: bash
+            working-directory: ${{ inputs.working-directory }}
+prevention:
+  - 'Never set working-directory on steps that use uses: — it is silently ignored'
+  - 'For composite actions that need a target directory, declare an explicit working-directory input'
+  - 'Use defaults.run.working-directory at job level to apply a directory to all run: steps'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsworking-directory'
+    label: 'steps[*].working-directory — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaultsrun'
+    label: 'defaults.run — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action'
+    label: 'Creating a composite action — GitHub Docs'

package/errors/triggers/pull-request-ready-for-review-type-missing.yml

@@ -0,0 +1,58 @@
+id: triggers-047
+title: 'pull_request default types exclude ready_for_review — draft-to-ready conversion skips CI'
+category: triggers
+severity: warning
+tags:
+  - pull_request
+  - draft
+  - ready_for_review
+  - types
+  - required-status-checks
+patterns:
+  - regex: 'on:\s*\n\s*pull_request\s*:'
+    flags: 'im'
+  - regex: 'pull_request\s*:\s*\n(?!\s*types)'
+    flags: 'im'
+error_messages:
+  - 'CI not triggered after converting draft pull request to ready for review'
+  - 'Required status check never ran after marking PR ready — branch protection blocking merge'
+root_cause: |
+  The pull_request event with no explicit types: list defaults to the activity types
+  [opened, synchronize, reopened]. When a contributor converts a draft PR to ready
+  for review, GitHub fires the ready_for_review activity type, which is absent from
+  the default set. The workflow never executes for this state transition, leaving the
+  PR without the required CI status checks. Branch protection rules then block merging
+  until the next push re-triggers CI.
+
+  This is one of the most frequently reported CI surprises in GitHub Community discussions,
+  particularly for teams that rely on draft PRs for work-in-progress reviews.
+fix: |
+  Explicitly declare the types list on the pull_request trigger and add ready_for_review:
+fix_code:
+  - language: yaml
+    label: 'Add ready_for_review to pull_request types'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - ready_for_review    # fires when a draft PR is marked ready for review
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - 'Always explicitly list pull_request types when your team uses draft PRs'
+  - 'Add ready_for_review when branch protection requires CI to pass before merge'
+  - 'Include converted_to_draft to re-trigger (or block) CI when PRs return to draft'
+  - 'Review required status check names after adding new trigger types to confirm they register'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'pull_request event types — GitHub Docs'
+  - url: 'https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request'
+    label: 'Changing the stage of a pull request — GitHub Docs'

package/package.json

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