@htekdev/actions-debugger 1.0.39 → 1.0.40

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.40",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",