@htekdev/actions-debugger 1.0.39 → 1.0.41

package/errors/caching-artifacts/setup-node-npm-cache-monorepo-lockfile-not-found.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-032
+title: 'setup-node cache: npm silently skips caching in monorepos — lockfile not at workspace root'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - setup-node
+  - npm
+  - cache
+  - monorepo
+  - lockfile
+  - cache-dependency-path
+  - silent-failure
+patterns:
+  - regex: "Warning: No file found for: package-lock\\.json"
+    flags: 'i'
+  - regex: 'No file found for.*No cache will be (saved|restored)'
+    flags: 'i'
+  - regex: 'cache-dependency-path.*not found|No lockfile found'
+    flags: 'i'
+error_messages:
+  - "Warning: No file found for: package-lock.json"
+  - "Warning: No file found for: yarn.lock"
+  - "Warning: No file found for: pnpm-lock.yaml"
+  - "No file found for: package-lock.json. No cache will be saved."
+root_cause: |
+  actions/setup-node with cache: 'npm' (or 'yarn' / 'pnpm') searches for the
+  package manager lockfile at the workspace root ($GITHUB_WORKSPACE) by default.
+
+  In monorepos where the lockfile lives in a subdirectory (apps/frontend/,
+  packages/api/, etc.), or when the workflow uses working-directory: to change
+  the build context, setup-node logs a warning and continues WITHOUT configuring
+  a cache. The step exits 0, making this a silent failure.
+
+  The result: npm ci (or yarn install / pnpm install) downloads all dependencies
+  from the network on every workflow run, as though no cache were configured.
+  Build times are identical to runs with no cache setting at all.
+
+  The warning message ("No file found for: package-lock.json") is easily missed
+  in long step logs and does not fail the step, so developers often go weeks
+  without noticing the cache was never active.
+
+  The same behavior applies when:
+  - yarn.lock is not at workspace root
+  - pnpm-lock.yaml is not at workspace root
+  - Multiple lockfiles exist across packages (only the first match is used
+    unless cache-dependency-path is explicitly set to a glob)
+fix: |
+  Use the cache-dependency-path input to specify the path to the lockfile
+  relative to the workspace root. Supports glob patterns for monorepos.
+
+  Single package in subdirectory:
+    cache-dependency-path: 'frontend/package-lock.json'
+
+  Multiple lockfiles across a monorepo:
+    cache-dependency-path: '**/package-lock.json'
+
+  Using a glob creates a combined cache key from all matched lockfiles. Any
+  change to any package lockfile invalidates the shared cache — this is
+  correct behavior for a monorepo where cross-package installs are common.
+fix_code:
+  - language: yaml
+    label: 'Single package in subdirectory — point cache-dependency-path at lockfile'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'
+                cache: 'npm'
+                # WRONG (omitted): setup-node looks at $GITHUB_WORKSPACE/package-lock.json
+                # and silently skips caching when not found there
+
+                # CORRECT: path relative to $GITHUB_WORKSPACE
+                cache-dependency-path: 'frontend/package-lock.json'
+
+            - name: Install dependencies
+              working-directory: frontend
+              run: npm ci
+  - language: yaml
+    label: 'Monorepo — cache all packages using glob pattern'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'
+                cache: 'npm'
+                # Glob matches all package-lock.json files anywhere in the repo
+                # Combined hash from all matched lockfiles forms the cache key
+                cache-dependency-path: '**/package-lock.json'
+
+            - name: Install root dependencies
+              run: npm ci
+
+            - name: Install frontend dependencies
+              working-directory: packages/frontend
+              run: npm ci
+prevention:
+  - 'Always set cache-dependency-path when the lockfile is not in the repository root'
+  - 'Use **/package-lock.json glob in monorepos to cover all packages with a single cache configuration'
+  - 'Verify caching is active by checking setup-node logs for "Cache restored successfully" or "Cache saved"'
+  - 'Check for "No file found for: package-lock.json" warnings as early signal that caching is silently disabled'
+  - 'When using working-directory: on install steps, ensure cache-dependency-path is also adjusted to match'
+docs:
+  - url: 'https://github.com/actions/setup-node#caching-global-packages-data'
+    label: 'actions/setup-node: Caching global packages data — cache-dependency-path input'
+  - url: 'https://github.com/actions/setup-node/issues/530'
+    label: 'actions/setup-node#530: cache: npm silently skips in monorepos without cache-dependency-path'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows — lockfile path configuration'

package/errors/concurrency-timing/cancel-in-progress-queued-run-status-never-posts.yml

@@ -0,0 +1,111 @@
+id: concurrency-timing-027
+title: 'Queued run cancelled by cancel-in-progress before any job starts — required status check never posts, PR permanently blocked'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - required-status-check
+  - branch-protection
+  - pr-blocked
+  - status-check
+patterns:
+  - regex: 'This run was cancelled because another run in the same concurrency group'
+    flags: 'i'
+  - regex: 'Waiting for.*status.*reported|Expected.*Waiting'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled because another run in the same concurrency group is in progress."
+  - "Waiting for status to be reported"
+root_cause: |
+  When cancel-in-progress: true cancels a workflow run that was queued but had
+  not yet started any job, GitHub does NOT post a status (pending, cancelled, or
+  failure) to the commit SHA. The run silently disappears from the run list.
+
+  Branch protection rules that require a specific status check (e.g., "CI / test")
+  only observe statuses that were posted. A run cancelled before its first job
+  starts never posts any status — not even "pending".
+
+  Impact on PRs with high push frequency:
+  1. Developer opens PR, pushes commit A — run starts, posts "pending"
+  2. Developer pushes fix commit B — run for A is cancelled, run for B is queued
+  3. Developer pushes commit C before B's run starts — B's run cancelled (never
+     started), run for C queued
+  4. Run for C finally starts and posts statuses
+  5. But if C is also cancelled before starting, the commit has NO status
+  6. Branch protection shows the required check as "Expected" forever
+  7. PR cannot be merged — the Merge button stays disabled indefinitely
+
+  This condition is self-healing if a new commit is pushed (starting a fresh
+  run that won't be cancelled), but in rapid-push scenarios the window persists
+  for many minutes and developers mistakenly believe the CI is broken.
+fix: |
+  Option 1 — Queue instead of cancel (safest):
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.ref }}"
+      cancel-in-progress: false
+
+  Runs queue behind one another; every commit eventually gets a status posted.
+
+  Option 2 — Status anchor job:
+  Add a minimal first job that completes instantly. Its "queued" + "in_progress"
+  status is posted to the commit SHA immediately, ensuring GitHub registers the
+  run before any cancellation can remove the status.
+
+  Option 3 — GitHub Actions recommended pattern:
+  Use cancel-in-progress: true for the expensive test jobs only, and have a
+  separate fast-posting job that always runs (not subject to concurrency group).
+fix_code:
+  - language: yaml
+    label: 'Queue runs instead of cancelling — every commit gets a status'
+    code: |
+      on:
+        pull_request:
+
+      concurrency:
+        # Queue instead of cancel — latest run waits, but always posts status
+        group: '${{ github.workflow }}-${{ github.ref }}'
+        cancel-in-progress: false
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: 'Status anchor job — posts status immediately before cancel window'
+    code: |
+      on:
+        pull_request:
+
+      concurrency:
+        group: '${{ github.workflow }}-${{ github.ref }}'
+        cancel-in-progress: true    # OK — anchor ensures status is posted first
+
+      jobs:
+        # Minimal job: completes in seconds, ensuring a status is recorded on the SHA
+        anchor:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "CI registered for ${{ github.sha }}"
+
+        # Expensive test job that is safe to cancel
+        test:
+          needs: anchor
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - 'Avoid cancel-in-progress: true on workflows whose jobs are required status checks for branch protection'
+  - 'Use cancel-in-progress: false with queuing semantics when PR mergeability must be preserved on every commit'
+  - 'Add a lightweight anchor job as the first required job to ensure a status posts before any cancel window closes'
+  - 'Monitor PRs stuck with Expected required checks — check whether recent commits had all their runs cancelled before starting'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency'
+    label: 'GitHub Actions: Using concurrency — cancel-in-progress behavior'
+  - url: 'https://github.com/orgs/community/discussions/21280'
+    label: 'GitHub Community: Required status check never posts when run cancelled before start (120+ reactions)'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging'
+    label: 'GitHub Docs: Required status checks — how commit statuses are evaluated for branch protection'

package/errors/concurrency-timing/step-timeout-not-supported-job-holds-runner.yml

@@ -0,0 +1,101 @@
+id: concurrency-timing-025
+title: 'No step-level timeout — a hung step holds the runner slot for up to 6 hours'
+category: concurrency-timing
+severity: limitation
+tags:
+  - timeout
+  - hung-step
+  - runner-slot
+  - step
+  - limitation
+  - self-hosted-runner
+patterns:
+  - regex: 'The runner has received a shutdown signal'
+    flags: 'i'
+  - regex: 'Error: The process.*timed out after \d+ minutes'
+    flags: 'i'
+  - regex: 'Canceling since the workflow was cancelled'
+    flags: 'i'
+error_messages:
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+  - "Error: The process '/usr/bin/bash' failed with exit code 124"
+  - "Canceling since the workflow was cancelled."
+root_cause: |
+  GitHub Actions supports timeout-minutes at the job level only. There is no
+  per-step timeout. A single run: step that hangs (network call blocked, test
+  suite deadlocked, subprocess waiting on stdin) holds the entire job until
+  the job-level timeout fires.
+
+  The default job timeout is 6 hours (360 minutes) for GitHub-hosted runners
+  and 35 days (unlimited in practice) for self-hosted runners. A single hung
+  step therefore silently consumes 6 hours of runner minutes and one complete
+  runner slot before GitHub kills the job.
+
+  Runner slot starvation is the secondary effect: while the hung job occupies a
+  runner, queued jobs wait. On self-hosted runners with limited capacity one
+  hung step can block an entire team's CI queue indefinitely.
+
+  This is a documented platform limitation tracked in actions/runner#1120
+  (220+ reactions, open since 2020) with no scheduled fix date.
+fix: |
+  Apply one of these workarounds depending on operating system:
+
+  Linux/macOS: Wrap the command with the system timeout utility (seconds):
+    run: timeout 300 ./integration-test.sh
+
+  Cross-platform: Use curl/Invoke-RestMethod built-in timeout options for
+  network calls, and test-runner native timeouts for test suites.
+
+  Always set timeout-minutes explicitly on every job to establish a hard upper
+  bound regardless of which step hangs.
+fix_code:
+  - language: yaml
+    label: 'Set explicit job timeout and use OS timeout for individual steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30    # explicit ceiling — never rely on 6h default
+
+          steps:
+            - uses: actions/checkout@v4
+
+            # Linux/macOS: system timeout (in seconds)
+            - name: Run integration tests
+              run: timeout 180 ./scripts/integration-test.sh
+
+            # Network call with built-in timeout
+            - name: Fetch external resource
+              run: |
+                curl --max-time 60 --retry 3 https://api.example.com/data -o data.json
+  - language: yaml
+    label: 'Self-hosted runner — conservative timeout prevents slot starvation'
+    code: |
+      jobs:
+        deploy:
+          runs-on: [self-hosted, production]
+          timeout-minutes: 45    # critical on self-hosted — hung jobs block all runners
+
+          steps:
+            - name: Deploy with timeout guard
+              shell: pwsh
+              run: |
+                $job = Start-Job { ./deploy.ps1 }
+                if (-not (Wait-Job $job -Timeout 120)) {
+                  Stop-Job $job
+                  throw "Deploy script timed out after 120s"
+                }
+                Receive-Job $job
+prevention:
+  - 'Always set explicit timeout-minutes on every job — never rely on the 6-hour GitHub-hosted default'
+  - 'Use OS-level timeout utilities (timeout on Linux/macOS) for individual network calls and scripts'
+  - 'Configure test-runner-native timeouts for test suites — they are more granular than job timeouts'
+  - 'Monitor runner queue depth on self-hosted runners — sudden growth often signals a hung step holding a slot'
+  - 'Set timeout-minutes: 5 on jobs you know should complete quickly to catch regressions early'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Actions: jobs.<id>.timeout-minutes — job-level timeout (no step-level equivalent)'
+  - url: 'https://github.com/actions/runner/issues/1120'
+    label: 'actions/runner#1120: Feature request — step-level timeout (220+ reactions, open since 2020)'
+  - url: 'https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits'
+    label: 'GitHub Actions usage limits — default job timeout values per runner type'

package/errors/concurrency-timing/workflow-dispatch-push-shared-concurrency-silent-cancel.yml

@@ -0,0 +1,104 @@
+id: concurrency-timing-026
+title: 'workflow_dispatch run silently cancelled when push to same branch shares the concurrency group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow-dispatch
+  - cancel-in-progress
+  - push
+  - manual-trigger
+  - silent-cancel
+patterns:
+  - regex: 'This run was cancelled because another run in the same concurrency group'
+    flags: 'i'
+  - regex: 'Canceling run due to.*concurrency group'
+    flags: 'i'
+  - regex: 'This run has been canceled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled because another run in the same concurrency group is in progress."
+  - "Canceling run due to a newer request for the same concurrency group."
+  - "This run has been canceled."
+root_cause: |
+  A common concurrency pattern groups runs by workflow name and ref:
+
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.ref }}"
+      cancel-in-progress: true
+
+  workflow_dispatch and push events on the same branch share identical
+  github.workflow and github.ref values, so they are placed in the same
+  concurrency slot.
+
+  A developer manually triggers a workflow_dispatch run (e.g., to deploy to
+  staging, run a migration, or kick off a release). While it is running, any
+  push to that branch — including a small documentation fix or revert — creates
+  a new run in the same concurrency slot and immediately cancels the in-progress
+  manual dispatch with no notification.
+
+  The developer discovers this only when checking on the deployment minutes
+  later to find it was cancelled mid-run. The automatic push run that replaced
+  it may be completely irrelevant to the manual operation.
+fix: |
+  Include github.event_name in the concurrency group key to give workflow_dispatch
+  and push events separate concurrency slots:
+
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}"
+      cancel-in-progress: true
+
+  workflow_dispatch runs now share a slot only with other workflow_dispatch runs
+  on the same branch, and push runs share a slot only with other push runs.
+
+  For deployment or migration workflows where even manual-vs-manual cancellation
+  is undesirable, use cancel-in-progress: false and let runs queue.
+fix_code:
+  - language: yaml
+    label: 'Include event_name in concurrency group — isolates manual from automatic triggers'
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+
+      concurrency:
+        # event_name isolates push and workflow_dispatch into separate concurrency slots
+        group: '${{ github.workflow }}-${{ github.event_name }}-${{ github.ref_name }}'
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Separate workflow file for manual operations — no cancel-in-progress'
+    code: |
+      # deploy-manual.yml — only triggered by workflow_dispatch
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment'
+              required: true
+              type: choice
+              options: [staging, production]
+
+      # No shared concurrency group with push workflows
+      concurrency:
+        group: 'manual-deploy-${{ github.event.inputs.environment }}'
+        # cancel-in-progress defaults to false — manual deploys queue, not cancel
+prevention:
+  - 'Always include github.event_name in concurrency group keys for workflows triggered by both push and workflow_dispatch'
+  - 'Use separate workflow files for manual deployment operations to avoid shared concurrency with automated triggers'
+  - 'Add a summary step or Telegram/Slack notification in the cleanup phase to alert when a run is cancelled mid-execution'
+  - 'Audit all concurrency group patterns when adding workflow_dispatch to an existing automated workflow'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency'
+    label: 'GitHub Actions: Using concurrency — group patterns and cancel-in-progress'
+  - url: 'https://github.com/orgs/community/discussions/5435'
+    label: 'GitHub Community: workflow_dispatch cancelled by push with same concurrency group'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub context: github.event_name property'

package/errors/permissions-auth/github-actor-vs-triggering-actor-rerun-bypass.yml

@@ -0,0 +1,111 @@
+id: permissions-auth-033
+title: 'github.actor frozen at original trigger time — github.triggering_actor differs on re-run, breaking actor-based access checks'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - github.actor
+  - github.triggering_actor
+  - re-run
+  - access-control
+  - if-condition
+  - silent-failure
+  - permissions
+patterns:
+  - regex: 'github\.triggering_actor|triggering_actor'
+    flags: 'i'
+  - regex: 'Skipping.*actor.*not.*allowed|actor.*not in.*allowlist'
+    flags: 'i'
+  - regex: 'Access denied.*github\.actor'
+    flags: 'i'
+error_messages:
+  - "Skipping deployment: actor 'original-bot' is not in the deployers allowlist"
+  - "Access denied: github.actor does not match the expected release account"
+root_cause: |
+  GitHub Actions provides two separate context properties for workflow actor identity:
+
+  github.actor           — the user or app that ORIGINALLY triggered the workflow run
+  github.triggering_actor — the user or app that triggered the CURRENT run attempt
+                            (reflects re-runs and re-trigger operations)
+
+  These values are identical for the first run of a workflow. They diverge when
+  the workflow is re-triggered via the "Re-run jobs" button, "Re-run failed jobs",
+  or the REST API re-run endpoint. In that case, github.actor still holds the
+  original requester's login while github.triggering_actor holds the person or
+  app that clicked re-run.
+
+  Two classes of silent failure result:
+
+  1. Security bypass: A workflow guards a deployment with
+     if: github.actor == 'deploy-bot'. A human clicks "Re-run" — github.actor
+     still shows 'deploy-bot' (original requester), so the guard passes and the
+     human inadvertently triggers a privileged deployment step.
+
+  2. Unintended block: A workflow allows deployments only for a specific release
+     manager by checking github.actor. A second authorized team member re-runs
+     the workflow — github.actor shows the original requester (someone else),
+     so the guard incorrectly blocks the re-run.
+
+  In both cases there is no error message indicating the actor mismatch — the
+  guard silently passes or silently blocks based on stale identity data.
+fix: |
+  For access control checks that should apply to WHO IS CURRENTLY RUNNING the
+  workflow (including re-runs), replace github.actor with github.triggering_actor.
+
+  For checks that must enforce the original requester (e.g., "only the PR author
+  can trigger this check"), use github.actor explicitly and document the intent.
+
+  For high-security deployment gates, use GitHub Environment protection rules
+  with required reviewers. Environment protection is enforced by GitHub platform
+  security rather than YAML if: conditions and cannot be bypassed by re-runs.
+fix_code:
+  - language: yaml
+    label: 'Use triggering_actor for re-run-aware access control'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # WRONG: github.actor is frozen at original trigger time
+            # github.actor still shows 'deploy-bot' even when a human re-runs
+            # - name: Gate check
+            #   if: github.actor != 'deploy-bot'
+            #   run: exit 1
+
+            # CORRECT: github.triggering_actor reflects who actually ran this attempt
+            - name: Gate check
+              if: github.triggering_actor != 'deploy-bot'
+              run: |
+                echo "::error::Deploy must be triggered by deploy-bot, got ${{ github.triggering_actor }}"
+                exit 1
+
+            - name: Deploy
+              run: ./deploy.sh
+  - language: yaml
+    label: 'Use environment protection rules for production deployments (preferred)'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production    # required reviewers enforced at platform level
+          steps:
+            - name: Deploy
+              env:
+                ACTOR: ${{ github.actor }}
+                TRIGGERED_BY: ${{ github.triggering_actor }}
+              run: |
+                echo "Original trigger: $ACTOR"
+                echo "This run triggered by: $TRIGGERED_BY"
+                ./deploy.sh
+prevention:
+  - 'Use github.triggering_actor (not github.actor) when the intent is to check who triggered the current run attempt'
+  - 'Prefer GitHub Environment protection rules and required reviewers over actor-based if: conditions for deployment gates'
+  - 'Document in each workflow whether actor checks use github.actor (original) or github.triggering_actor (current)'
+  - 'Test actor-based gates by having a second authorized user re-run the workflow to verify the check fires as expected'
+  - 'Never use github.actor alone for security-sensitive production deployment gates — it is not re-run-aware'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'github context — github.actor vs github.triggering_actor properties'
+  - url: 'https://github.blog/changelog/2022-08-09-github-actions-re-run-workflows-and-jobs/'
+    label: 'GitHub Changelog 2022-08-09: Re-run workflows and jobs — introducing triggering_actor'
+  - url: 'https://github.com/orgs/community/discussions/27154'
+    label: 'GitHub Community: github.actor vs github.triggering_actor for re-run access control'

package/errors/silent-failures/upload-artifact-path-ignores-working-directory.yml

@@ -0,0 +1,103 @@
+id: silent-failures-044
+title: 'upload-artifact path patterns resolved from workspace root — working-directory setting ignored'
+category: silent-failures
+severity: silent-failure
+tags:
+  - upload-artifact
+  - working-directory
+  - path
+  - glob
+  - artifacts
+  - workspace
+patterns:
+  - regex: 'No files were found with the provided path'
+    flags: 'i'
+  - regex: 'Warning: No files were found with the provided path'
+    flags: 'i'
+  - regex: 'artifact.*no files.*found|no files.*artifact'
+    flags: 'i'
+error_messages:
+  - "Error: No files were found with the provided path: dist/build.zip. No artifacts will be uploaded."
+  - "Warning: No files were found with the provided path: *.tar.gz. No artifacts will be uploaded."
+  - "No files were found with the provided path: output/*.zip"
+root_cause: |
+  The path: input in actions/upload-artifact (all versions) is always resolved
+  relative to $GITHUB_WORKSPACE (the repository root), regardless of any
+  working-directory: setting on the step or enclosing job.
+
+  Developers who set working-directory: dist at the job level or on the step
+  and then specify path: *.js or path: build.zip expect the glob to be evaluated
+  from within dist/. Instead, the action evaluates it from workspace root, finds
+  no matching files, and either warns and uploads nothing (silent-failure) or
+  fails the step entirely depending on if-no-files-found setting.
+
+  The working-directory: context is respected only by run: shell steps for
+  command execution. It is not propagated to uses: action inputs — actions
+  receive path inputs as raw strings and resolve them internally from GITHUB_WORKSPACE.
+
+  The same behavior applies to actions/download-artifact path: inputs and to
+  other actions that accept file path parameters (e.g., docker/build-push-action
+  context: and file: inputs also require workspace-relative paths).
+fix: |
+  Prefix all path: patterns with the subdirectory path relative to GITHUB_WORKSPACE.
+
+  Instead of:
+    working-directory: dist
+    path: build.zip
+
+  Use:
+    path: dist/build.zip
+
+  Or to upload an entire directory tree:
+    path: dist/
+
+  Set if-no-files-found: error to convert the silent warning into a visible
+  failure so path mistakes are caught immediately rather than silently producing
+  empty or missing artifacts downstream.
+fix_code:
+  - language: yaml
+    label: 'Use workspace-relative path instead of relying on working-directory'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              working-directory: dist    # only affects this run: step
+              run: npm run build
+
+            # WRONG: path: build.zip searches workspace root, not dist/
+            # - uses: actions/upload-artifact@v4
+            #   with:
+            #     name: release
+            #     path: build.zip
+
+            # CORRECT: include the subdirectory in the path
+            - uses: actions/upload-artifact@v4
+              with:
+                name: release
+                path: dist/build.zip    # relative to GITHUB_WORKSPACE
+                if-no-files-found: error
+  - language: yaml
+    label: 'Upload all files from a subdirectory and fail fast on missing files'
+    code: |
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-files
+          path: dist/               # uploads entire dist/ directory tree
+          if-no-files-found: error  # fail fast instead of silent warning
+prevention:
+  - 'Always write path: patterns in upload-artifact relative to GITHUB_WORKSPACE (repository root), not working-directory'
+  - 'Set if-no-files-found: error on every upload-artifact step to catch path mistakes immediately'
+  - 'Verify artifact contents in the Actions UI after the first run to confirm the correct files were captured'
+  - 'Remember that working-directory: only affects run: shell steps — uses: action inputs are always workspace-relative'
+  - 'Use ${{ github.workspace }} to build absolute paths when the relative path is ambiguous'
+docs:
+  - url: 'https://github.com/actions/upload-artifact#inputs'
+    label: 'actions/upload-artifact inputs — path field documentation'
+  - url: 'https://github.com/actions/upload-artifact/issues/232'
+    label: 'upload-artifact#232: path is resolved relative to workspace root, not working-directory (community report)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables'
+    label: 'GITHUB_WORKSPACE default environment variable — GitHub Docs'

package/errors/triggers/required-status-check-paths-filter-pr-stuck.yml

@@ -0,0 +1,119 @@
+id: triggers-031
+title: 'Required status check never satisfied when workflow uses paths: filter — PR permanently blocked'
+category: triggers
+severity: error
+tags:
+  - required-status-check
+  - paths-filter
+  - pull-request
+  - branch-protection
+  - PR-blocked
+  - monorepo
+  - status-check
+patterns:
+  - regex: 'Required status check.*is expected'
+    flags: 'i'
+  - regex: 'Merging is blocked.*required status check'
+    flags: 'i'
+  - regex: 'Waiting for status to be reported'
+    flags: 'i'
+error_messages:
+  - "Required status check 'CI / build' is expected — 1 pending check"
+  - "Merging is blocked: 1 required status check has not completed"
+  - "Waiting for status to be reported"
+root_cause: |
+  When a GitHub Actions workflow uses on: push: paths: or on: pull_request: paths:
+  filter AND that workflow's job name is configured as a required status check in
+  branch protection rules, a critical gap emerges.
+
+  If a pull request does NOT modify any files matching the paths: filter, the
+  workflow is skipped entirely — no workflow run is created and no check status
+  is posted to the commit. GitHub branch protection interprets a missing status
+  check as "pending" (not as "skipped" or "passed"), which permanently blocks the
+  PR from merging.
+
+  This is the most common misconfiguration in monorepo setups where teams add
+  per-service CI: a workflow for service-A runs only when src/service-a/** changes.
+  Adding this workflow's job as a required status check then breaks ALL other PRs
+  that don't touch service-A — they are blocked forever waiting for a check that
+  will never run.
+
+  The same issue occurs with paths-ignore: if ALL changed files match the ignore
+  patterns, the workflow is skipped and the required check is never posted.
+
+  Note: GitHub does not automatically treat a "skipped" workflow as passing a
+  required status check. The job must explicitly run and succeed.
+fix: |
+  Remove the paths: filter from the on: trigger and instead use dorny/paths-filter
+  or tj-actions/changed-files inside the workflow to detect changed files. The
+  workflow always runs (posting a check status) but skips expensive build steps
+  when irrelevant files changed.
+
+  Add a final ci-complete or always-pass job that runs with if: always() and
+  depends on the conditional jobs. Configure this final job name as the required
+  status check. It posts a success status for all PRs, whether or not the
+  upstream jobs ran.
+fix_code:
+  - language: yaml
+    label: 'Replace paths: filter with internal file detection — always post a check status'
+    code: |
+      name: Service A CI
+
+      on:
+        pull_request:
+          branches: [main]
+          # REMOVE the paths: filter that prevents check from running on non-matching PRs
+          # paths:
+          #   - src/service-a/**
+
+      jobs:
+        detect-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            service-a-changed: ${{ steps.filter.outputs.service-a }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  service-a:
+                    - 'src/service-a/**'
+
+        build:
+          needs: detect-changes
+          if: needs.detect-changes.outputs.service-a-changed == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build-service-a
+
+        # Required status check name: "Service A CI / ci-complete"
+        # This job ALWAYS runs and posts a check — satisfies branch protection for all PRs
+        ci-complete:
+          needs: [detect-changes, build]
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Evaluate build result
+              run: |
+                if [[ "${{ needs.build.result }}" == "failure" ]]; then
+                  echo "Build failed"
+                  exit 1
+                fi
+                echo "CI complete (build skipped or passed)"
+prevention:
+  - 'Never add a required status check on a workflow that has a paths: filter — the check will be missing for non-matching PRs'
+  - 'Use paths-filter action inside the workflow instead of on.pull_request.paths to keep the workflow always running'
+  - 'Add a ci-complete job with if: always() as the required status check — not the individual build job'
+  - 'Test branch protection + paths filter by opening a PR that changes only unrelated files before enabling required checks'
+  - 'Document in your monorepo contributing guide that required checks use the internal paths-filter pattern'
+docs:
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging'
+    label: 'About protected branches — require status checks before merging'
+  - url: 'https://github.com/orgs/community/discussions/20548'
+    label: 'GitHub Community: Required status check never satisfies when workflow has paths filter (30+ reactions)'
+  - url: 'https://github.com/dorny/paths-filter'
+    label: 'dorny/paths-filter — recommended replacement for workflow-level paths: filter'
+  - url: 'https://github.com/orgs/community/discussions/44490'
+    label: 'GitHub Community: paths filter skips required checks causing PR stuck (additional discussion)'

package/errors/yaml-syntax/runs-on-label-and-matching-infinite-queue.yml

@@ -0,0 +1,97 @@
+id: yaml-syntax-034
+title: 'runs-on label array requires ALL labels to match (AND logic) — job queues indefinitely when no runner qualifies'
+category: yaml-syntax
+severity: error
+tags:
+  - runs-on
+  - self-hosted
+  - labels
+  - runner-matching
+  - AND-logic
+  - job-queue
+  - infinite-wait
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+  - regex: 'Could not find any available self-hosted runner that matches the required labels'
+    flags: 'i'
+  - regex: 'No hosted runner matching the labels.*was found'
+    flags: 'i'
+error_messages:
+  - "Waiting for a runner to pick up this job"
+  - "Could not find any available self-hosted runner that matches the required labels: self-hosted, linux, arm64, fast-ssd"
+  - "No hosted runner matching the labels ['self-hosted', 'linux', 'gpu'] was found"
+root_cause: |
+  When runs-on: specifies an array of labels, GitHub requires a runner to have
+  ALL of the listed labels simultaneously (AND logic, not OR). A runner registered
+  with labels [self-hosted, linux, x64] will NOT match
+  runs-on: [self-hosted, linux, arm64] because it is missing the arm64 label,
+  even though it has two of the three required labels.
+
+  Common causes of permanent queueing:
+  - Combining labels from different runner types in one runs-on: array, expecting
+    any runner matching any label to pick up the job
+  - A typo in one label (e.g., "arm64" vs "aarch64") making the full set unmatchable
+  - Adding a new label requirement without ensuring at least one runner carries it
+  - Using a label that was renamed on the runner registration but not updated in workflows
+  - Combining GitHub-hosted runner identifiers with self-hosted labels
+    (e.g., [ubuntu-latest, self-hosted]) — GitHub-hosted runners do not carry
+    the self-hosted label, so this combination never matches any runner
+
+  The job queues indefinitely with "Waiting for a runner to pick up this job" and
+  never times out automatically unless job timeout-minutes or org-level timeout
+  limits are configured. The error message lists all required labels but does not
+  indicate which specific label is unmatched.
+fix: |
+  Ensure at least one registered runner has EVERY label in the runs-on: array.
+  Check Settings > Actions > Runners to verify exact label sets on each runner.
+
+  For different runner types (e.g., x64 vs ARM), use separate jobs rather than
+  a single job with an impossible label combination. For OR semantics across
+  runner types, use a matrix strategy.
+
+  For GitHub-hosted runners, use a single label string (ubuntu-latest,
+  windows-latest, macos-latest) not an array.
+fix_code:
+  - language: yaml
+    label: 'Use only labels that ALL exist on at least one registered runner'
+    code: |
+      jobs:
+        # WRONG: no single runner has both fast-ssd AND arm64 labels
+        # build:
+        #   runs-on: [self-hosted, linux, arm64, fast-ssd]
+
+        # CORRECT: use only labels that exist together on one runner
+        build:
+          runs-on: [self-hosted, linux, arm64]   # matches a runner with all three
+
+        # CORRECT for GitHub-hosted: single string label
+        test:
+          runs-on: ubuntu-latest
+  - language: yaml
+    label: 'Use matrix to target multiple runner types (OR semantics)'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              runner:
+                - ubuntu-latest
+                - [self-hosted, linux, arm64]
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'Treat runs-on: arrays as requiring ALL labels on one runner simultaneously — never use them as OR matching'
+  - 'Keep self-hosted runner label sets minimal (2-3 labels) to reduce the risk of unmatched combinations'
+  - 'Audit all workflow runs-on: references when renaming or removing runner labels — old labels cause indefinite queueing'
+  - 'Verify exact label sets in GitHub Settings > Actions > Runners before writing runs-on: arrays'
+  - 'Set a job-level timeout-minutes to prevent stuck jobs from blocking runners indefinitely'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job#choosing-self-hosted-runners'
+    label: 'Choosing self-hosted runners — label matching behavior (AND semantics)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners'
+    label: 'Using labels with self-hosted runners'
+  - url: 'https://github.com/orgs/community/discussions/25033'
+    label: 'GitHub Community: Self-hosted runner label AND matching — job queues indefinitely'

package/package.json

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