@htekdev/actions-debugger 1.0.38 → 1.0.40

package/errors/caching-artifacts/cache-legacy-service-decommission-url-override-fail.yml

@@ -0,0 +1,120 @@
+id: caching-artifacts-031
+title: 'Cache failures from manually-overridden ACTIONS_CACHE_URL after legacy service decommission (April 2025)'
+category: caching-artifacts
+severity: error
+tags:
+  - cache
+  - legacy-service
+  - ACTIONS_CACHE_URL
+  - service-migration
+  - brownout
+  - self-hosted
+patterns:
+  - regex: 'ACTIONS_CACHE_URL.*403|ACTIONS_CACHE_URL.*503|ACTIONS_CACHE_URL.*Connection refused'
+    flags: 'i'
+  - regex: 'Cache service responded with (403|503|5\d\d)'
+    flags: 'i'
+  - regex: 'Failed to restore cache entry\. Exiting\.\.\.'
+    flags: 'i'
+  - regex: 'Unable to reserve cache with key.*ACTIONS_CACHE_URL'
+    flags: 'i'
+error_messages:
+  - "Cache service responded with 503"
+  - "Cache service responded with 403"
+  - "Failed to restore cache entry. Exiting..."
+  - "Unable to reserve cache with key"
+  - "Error: ECONNREFUSED connecting to ACTIONS_CACHE_URL"
+root_cause: |
+  GitHub migrated all customers to a new cache service backend in early 2025
+  and decommissioned the legacy service on April 15, 2025. Prior to decommission,
+  brownout windows were scheduled on April 1 and April 8 (each 4-8 hours).
+
+  Workflows that explicitly override ACTIONS_CACHE_URL, ACTIONS_RESULTS_URL, or
+  ACTIONS_RUNTIME_URL continue routing requests to the decommissioned endpoint,
+  causing 403 or 503 responses. The cache action reports "Failed to restore cache
+  entry" or "Unable to reserve cache" and either skips caching silently or fails
+  the step (depending on fail-on-cache-miss settings).
+
+  Common sources of stale overrides:
+  - Third-party self-hosted runner software (ARC add-ons, Buildkite agents, etc.)
+    that inject a corporate cache proxy URL into the runner environment
+  - Composite actions or reusable workflows with hardcoded env var overrides
+    copied from pre-migration documentation
+  - Container images with ENV ACTIONS_CACHE_URL set in their Dockerfile,
+    inherited by container jobs and overriding the runner-injected value
+  - Enterprise self-hosted runner configurations in on-premises GitHub instances
+    that still point to a proxy configured for the old cache service API
+
+  The runner agent always injects the correct new-service values at job startup.
+  Any explicit override — even one set a millisecond earlier — takes precedence
+  and silently routes to the wrong endpoint.
+fix: |
+  Remove all explicit overrides of ACTIONS_CACHE_URL, ACTIONS_RESULTS_URL, and
+  ACTIONS_RUNTIME_URL from:
+  - Workflow env: blocks (top-level, job-level, and step-level)
+  - Composite action env blocks
+  - Reusable workflow env blocks
+  - Container image Dockerfiles (ENV directives)
+  - Self-hosted runner startup scripts and systemd unit files
+  - ARC runner controller configuration and any environment-injection middleware
+
+  Let the runner agent inject the correct values automatically at job startup.
+  These values are ephemeral per-job tokens — they cannot be cached or pre-set
+  and must come from the runner agent.
+
+  For self-hosted setups using a corporate cache proxy, update the proxy
+  to forward requests to the new service endpoint format, or decommission the
+  proxy if it is no longer required.
+fix_code:
+  - language: yaml
+    label: 'Remove ACTIONS_CACHE_URL override from workflow — let runner inject correct value'
+    code: |
+      # WRONG: overriding cache service URL causes failures after April 2025
+      # env:
+      #   ACTIONS_CACHE_URL: https://my-corp-proxy.example.com/_apis/artifactcache/
+      #   ACTIONS_RESULTS_URL: https://my-corp-proxy.example.com/_apis/
+      #   ACTIONS_RUNTIME_URL: https://my-corp-proxy.example.com/
+
+      # CORRECT: remove all overrides, let the runner inject the values
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          steps:
+            - uses: actions/checkout@v4
+            - name: Cache dependencies
+              uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            - name: Install
+              run: npm ci
+  - language: yaml
+    label: 'Audit container images for hardcoded ACTIONS_CACHE_URL'
+    code: |
+      # In your Dockerfile — remove any hardcoded cache service URL
+      # FROM ubuntu:22.04
+      # ENV ACTIONS_CACHE_URL=https://...  ← REMOVE: causes failures after April 2025
+
+      # In your workflow — do not set cache URL env vars in container definitions
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: myimage:latest
+            # Do not add env overrides for ACTIONS_CACHE_URL here
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: ~/.cache/pip
+                key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+prevention:
+  - 'Never hardcode ACTIONS_CACHE_URL, ACTIONS_RESULTS_URL, or ACTIONS_RUNTIME_URL in workflows, container images, or runner configs'
+  - 'Audit third-party composite actions and runner middleware for injected cache URL overrides after any GitHub cache service migration'
+  - 'Subscribe to the GitHub Changelog (github.blog/changelog) to receive advance notice of cache service migrations and brownout schedules'
+  - 'Upgrade to actions/cache@v4 or later — the v4 client was updated to use the new service API and is the supported path forward'
+  - 'Add a pre-flight check step on self-hosted runners that logs the injected ACTIONS_CACHE_URL to detect unexpected overrides'
+docs:
+  - url: 'https://github.blog/changelog/2025-03-20-notification-of-upcoming-breaking-changes-in-github-actions/'
+    label: 'GitHub Changelog: Upcoming breaking changes — legacy cache service decommission (March 2025)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'Caching dependencies to speed up workflows — actions/cache@v4'

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/runner-environment/container-job-rootless-user-workspace-eacces.yml

@@ -0,0 +1,103 @@
+id: runner-environment-097
+title: 'Container job with non-root Docker user fails with EACCES on workspace and command files'
+category: runner-environment
+severity: error
+tags:
+  - container-jobs
+  - non-root
+  - rootless
+  - permissions
+  - EACCES
+  - docker
+  - workspace
+patterns:
+  - regex: 'EACCES.*permission denied.*_runner_file_commands|permission denied.*_runner_file_commands'
+    flags: 'i'
+  - regex: 'permission denied.*GITHUB_ENV|permission denied.*GITHUB_OUTPUT|permission denied.*GITHUB_PATH|permission denied.*GITHUB_STEP_SUMMARY'
+    flags: 'i'
+  - regex: 'could not lock config file.*Permission denied'
+    flags: 'i'
+  - regex: 'EACCES.*permission denied.*__w|permission denied.*github/workspace'
+    flags: 'i'
+error_messages:
+  - "Error: EACCES: permission denied, open '/home/runner/work/_temp/_runner_file_commands/set_env_'"
+  - "Error: EACCES: permission denied, open '/__w/_temp/_runner_file_commands/add_path_'"
+  - "error: could not lock config file /home/runner/work/repo/.git/config: Permission denied"
+  - "EACCES: permission denied, open '/github/workspace/_temp/_runner_file_commands/'"
+root_cause: |
+  When a workflow uses a container job (jobs.<id>.container), the GitHub Actions
+  runner creates the workspace directories, .git directory, and all special command
+  files (GITHUB_ENV, GITHUB_OUTPUT, GITHUB_PATH, GITHUB_STEP_SUMMARY) as root UID
+  on the host before starting the container.
+
+  If the container image runs as a non-root user — via a USER directive in the
+  Dockerfile, docker run --user, or a Kubernetes securityContext.runAsUser setting —
+  that user has no write access to the root-owned files and directories. Every step
+  that writes to GITHUB_ENV, GITHUB_OUTPUT, GITHUB_PATH, or GITHUB_STEP_SUMMARY
+  fails with EACCES: permission denied. The checkout step also fails because git
+  cannot write the lock file for the config.
+
+  The runner does not automatically adjust ownership, set ACLs, or apply mount
+  options to make the workspace writable by non-root container users. This is a
+  known long-standing platform limitation tracked in runner#2411 (30 reactions)
+  with no built-in fix as of 2026. The issue also affects ARC (actions-runner-controller)
+  Kubernetes runners when the pod securityContext sets a non-root runAsUser.
+fix: |
+  Option 1 — Add `options: --user root` to the container definition.
+  This overrides the container USER and runs job steps as root, granting
+  full access to all runner-created files.
+
+  Option 2 — Set fsGroup in Kubernetes/ARC pod spec so mounted directories
+  are group-writable and the container's supplemental group matches.
+
+  Option 3 — Use a privileged init step (--user 0) to chown the workspace
+  to the container's non-root UID before executing actual build steps.
+
+  Option 4 — Build the container image with UID 1001 (the runner UID on
+  GitHub-hosted runners) instead of a custom non-root UID, so ownership
+  matches automatically.
+fix_code:
+  - language: yaml
+    label: 'Force container to run as root with options: --user root'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: myapp:latest       # Has a non-root USER in its Dockerfile
+            options: --user root      # Override: run job steps as root
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build
+  - language: yaml
+    label: 'Set fsGroup in ARC RunnerSet to make workspace group-writable'
+    code: |
+      apiVersion: actions.github.com/v1alpha1
+      kind: RunnerSet
+      metadata:
+        name: my-runners
+      spec:
+        template:
+          spec:
+            securityContext:
+              fsGroup: 1001          # Match runner UID so workspace is accessible
+            containers:
+              - name: runner
+                image: ghcr.io/actions/actions-runner:latest
+                securityContext:
+                  runAsUser: 1001
+                  runAsGroup: 1001
+prevention:
+  - 'Prefer running container jobs as root or as UID 1001 to match the runner workspace ownership'
+  - 'Test container images locally with docker run --user <uid> to catch permission issues before CI'
+  - 'Document the --user root workaround in workflow templates that use custom container images'
+  - 'Consider using a job-level container for tool availability only, keeping privileged steps on the host runner'
+  - 'When building custom runner images, set USER to UID 1001 to match GitHub-hosted runner conventions'
+docs:
+  - url: 'https://github.com/actions/runner/issues/2411'
+    label: 'runner#2411: Runner does not set proper permissions for mounted folders in rootless container jobs (30 reactions)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container'
+    label: 'Running jobs in a container — options field and container configuration'
+  - url: 'https://github.com/actions/runner/issues/3290'
+    label: 'runner#3290: Kubernetes container pods fail with EACCES when using a custom user'

package/errors/runner-environment/self-hosted-runsvc-zero-bytes-auto-update.yml

@@ -0,0 +1,112 @@
+id: runner-environment-096
+title: 'Self-hosted runner runsvc.sh corrupted to 0 bytes after auto-update'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - auto-update
+  - runsvc
+  - systemd
+  - service-restart
+patterns:
+  - regex: 'runsvc\.sh.*0 bytes|0 bytes.*runsvc\.sh'
+    flags: 'i'
+  - regex: 'code=exited.*status=203/EXEC|status=203/EXEC'
+    flags: 'i'
+  - regex: 'Failed to start GitHub Actions Runner'
+    flags: 'i'
+  - regex: 'bin/runsvc\.sh.*Syntax error.*end of file'
+    flags: 'i'
+error_messages:
+  - "(code=exited, status=203/EXEC)"
+  - "Failed to start GitHub Actions Runner (svc.sh)"
+  - "bin/runsvc.sh: 1: Syntax error: Unexpected end of file"
+  - "bin.2.334.0/runsvc.sh: 0 bytes"
+root_cause: |
+  When a self-hosted runner auto-updates from v2.328.0 to v2.334.0 (and some
+  adjacent version pairs), a race condition in the update file-extraction process
+  sometimes writes the new bin.{version}/runsvc.sh as 0 bytes instead of the
+  correct shell script content.
+
+  The currently-running listener operates from in-memory state and continues
+  accepting and completing jobs normally — so the runner appears healthy in
+  the GitHub Actions UI and the corruption is not immediately visible. The
+  bin/runsvc.sh symlink quietly points to the corrupted 0-byte file.
+
+  On the next service restart (host reboot, manual systemctl restart, OOM kill,
+  scheduled maintenance window), systemd attempts to execute the 0-byte runsvc.sh,
+  receives Status=203/EXEC (exec format error because the file is empty), and the
+  runner fails to start entirely — dropping all pending and future jobs.
+
+  The failure is especially hard to diagnose because the runner appears fully
+  online right up to the restart event. Runners in pools that restart infrequently
+  may run corrupted for days before the symptom appears.
+fix: |
+  Immediate recovery:
+  1. Check if runsvc.sh is 0 bytes:
+       ls -lh /path/to/runner/bin/runsvc.sh
+  2. If 0 bytes, stop the service and re-download the runner package at the
+     same version, or manually copy runsvc.sh from a known-good runner
+     installation of the same version.
+  3. Restart the service and confirm it comes up cleanly before re-enabling
+     job acceptance.
+
+  Preventive measures:
+  - Disable auto-update (--no-auto-update flag during registration) and manage
+    runner version upgrades manually during maintenance windows.
+  - Add a startup health check (see fix_code) that verifies runsvc.sh is
+    non-zero before the service is considered ready.
+  - For ephemeral runners, use container restart policies that detect the
+    0-byte condition and re-register a fresh runner instead of recycling
+    a corrupted one.
+fix_code:
+  - language: yaml
+    label: 'Detect corrupted runsvc.sh in a pre-job health check step'
+    code: |
+      jobs:
+        preflight:
+          runs-on: [self-hosted, linux]
+          steps:
+            - name: Verify runner service script integrity
+              shell: bash
+              run: |
+                RUNNER_SVC="$(dirname "$(realpath "$0")")/../bin/runsvc.sh"
+                if [ ! -s "$RUNNER_SVC" ]; then
+                  echo "::error::runsvc.sh is 0 bytes — runner update corrupted the service script. Re-register this runner."
+                  exit 1
+                fi
+                echo "runsvc.sh OK ($(wc -c < "$RUNNER_SVC") bytes)"
+  - language: yaml
+    label: 'Pin runner version and disable auto-update via ARC RunnerSet spec'
+    code: |
+      # actions-runner-controller RunnerSet — pin version, disable auto-update
+      apiVersion: actions.github.com/v1alpha1
+      kind: RunnerSet
+      metadata:
+        name: my-runners
+      spec:
+        githubConfigUrl: https://github.com/my-org/my-repo
+        githubConfigSecret: controller-manager
+        minRunners: 2
+        maxRunners: 10
+        template:
+          spec:
+            containers:
+              - name: runner
+                image: ghcr.io/actions/actions-runner:2.334.0   # pin version
+                env:
+                  - name: DISABLE_RUNNER_UPDATE
+                    value: '1'
+prevention:
+  - 'Pin runner version with --no-auto-update and upgrade manually during maintenance windows'
+  - 'Monitor runner systemd units with alerting on failed states before jobs queue up'
+  - 'Use ephemeral runners (--ephemeral flag) so each job gets a freshly registered runner, avoiding accumulated update corruption'
+  - 'After any auto-update event, verify that bin/runsvc.sh is non-zero before accepting production jobs'
+  - 'Run a nightly canary workflow that exercises a restart-then-run cycle on self-hosted pools'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4421'
+    label: 'runner#4421: runsvc.sh sometimes 0 bytes after auto-update from 2.328.0 to 2.334.0 (May 2026)'
+  - 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 — runner lifecycle management'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-version-updates'
+    label: 'Self-hosted runner version updates'

package/errors/silent-failures/github-workspace-incorrect-inside-container-job.yml

@@ -0,0 +1,123 @@
+id: silent-failures-043
+title: 'github.workspace and runner.workspace return host paths, not container paths, inside container jobs'
+category: silent-failures
+severity: silent-failure
+tags:
+  - container-jobs
+  - github-context
+  - workspace
+  - path-mismatch
+  - expressions
+  - silent
+patterns:
+  - regex: '\$\{\{\s*github\.workspace\s*\}\}.*container|\$\{\{\s*runner\.workspace\s*\}\}.*container'
+    flags: 'i'
+  - regex: '/home/runner/work/[^/]+/[^/]+.*no such file|not found.*home/runner/work'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  Inside container jobs, `${{ github.workspace }}` and `${{ runner.workspace }}`
+  resolve to the HOST-side path (e.g., /home/runner/work/repo/repo), not the
+  path that the container actually sees at runtime (e.g., /github/workspace or
+  /__w/repo/repo depending on the runner type).
+
+  The container mounts the workspace at a different path than the host. Any
+  expression using these context values to construct file paths, Docker build
+  contexts, artifact paths, or shell script arguments will silently resolve to
+  the wrong location inside the container — either a non-existent path or an
+  unexpected host directory leaked into the container mount namespace.
+
+  By contrast, the GITHUB_WORKSPACE and RUNNER_WORKSPACE environment variables
+  ARE injected with the correct container-visible paths. Only the expression
+  context values (${{ github.workspace }}) are wrong. This inconsistency is the
+  core trap: developers expect context and env var to be equivalent, but inside
+  containers they diverge.
+
+  No error is raised — wrong paths are silently accepted by shells and tools,
+  causing subtly incorrect behavior: files not found, wrong directory used for
+  builds, artifacts uploaded from wrong paths, or test results pointing to
+  non-existent locations.
+
+  Tracked in runner#2058 (81 reactions, 13 confused reactions) as a known bug
+  with no built-in fix as of 2026.
+fix: |
+  Use the GITHUB_WORKSPACE environment variable instead of the
+  ${{ github.workspace }} expression inside container job steps. The env var
+  is injected by the runner with the correct container-visible path.
+
+  Similarly, use RUNNER_WORKSPACE instead of ${{ runner.workspace }}.
+
+  For Docker build contexts and tool paths that require absolute paths, use
+  the container-visible path directly:
+  - GitHub-hosted runners: /github/workspace
+  - ARC/self-hosted: /__w/<repo-name>/<repo-name> (verify with pwd in first step)
+
+  Alternatively, use relative paths (.) wherever possible to avoid the
+  host/container path discrepancy entirely.
+fix_code:
+  - language: yaml
+    label: 'Use GITHUB_WORKSPACE env var instead of ${{ github.workspace }} inside container steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: myapp-builder:latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # WRONG: returns host path, not the container-visible mount path
+            # - name: Build
+            #   run: cd "${{ github.workspace }}" && make build
+
+            # CORRECT: GITHUB_WORKSPACE is set to the container-visible path
+            - name: Build
+              run: |
+                echo "Container workspace: $GITHUB_WORKSPACE"
+                cd "$GITHUB_WORKSPACE" && make build
+  - language: yaml
+    label: 'Use relative paths for Docker build context inside container jobs'
+    code: |
+      jobs:
+        docker-in-docker:
+          runs-on: ubuntu-latest
+          container:
+            image: docker:24
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build image
+              run: |
+                # Use . (current dir) not ${{ github.workspace }} for build context
+                docker build -t myimage:latest .
+
+                # If absolute path needed, use the env var:
+                docker build -t myimage:latest "$GITHUB_WORKSPACE"
+  - language: yaml
+    label: 'Debug step to reveal the actual container workspace path'
+    code: |
+      jobs:
+        debug:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:22.04
+          steps:
+            - name: Show path discrepancy
+              run: |
+                echo "Host path via context (WRONG inside container):"
+                echo "  github.workspace = ${{ github.workspace }}"
+                echo ""
+                echo "Container-visible path via env var (CORRECT):"
+                echo "  GITHUB_WORKSPACE = $GITHUB_WORKSPACE"
+                echo ""
+                echo "Actual current directory: $(pwd)"
+prevention:
+  - 'Never use ${{ github.workspace }} or ${{ runner.workspace }} expressions inside container job steps — they return host paths'
+  - 'Use the GITHUB_WORKSPACE and RUNNER_WORKSPACE environment variables for all path references inside containers'
+  - 'Use relative paths wherever possible in container steps to avoid the host/container path mismatch entirely'
+  - 'Add a debug step printing both the context value and the env var when authoring new container workflows'
+  - 'Test container-based workflows locally with nektos/act to surface path resolution issues before CI'
+docs:
+  - url: 'https://github.com/actions/runner/issues/2058'
+    label: 'runner#2058: github.workspace and runner.workspace are incorrect inside container jobs (81 reactions)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container'
+    label: 'Running jobs in a container — environment variables and context values'

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.38",
+  "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",