@htekdev/actions-debugger 1.0.65 → 1.0.67

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

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

package/errors/runner-environment/ubuntu-24-docker-compose-v1-removed.yml

@@ -0,0 +1,95 @@
+id: runner-environment-125
+title: "ubuntu-22.04/24.04 Runners: docker-compose (v1) Binary Removed — Use docker compose v2"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-compose
+  - ubuntu-22
+  - ubuntu-24
+  - compose-v2
+  - breaking-change
+patterns:
+  - regex: 'docker-compose:\s*(command not found|not found)'
+    flags: 'i'
+  - regex: '/usr/bin/docker-compose:\s*No such file or directory'
+    flags: 'i'
+  - regex: 'exec\s+"docker-compose":\s*executable file not found'
+    flags: 'i'
+error_messages:
+  - "docker-compose: command not found"
+  - "/usr/bin/docker-compose: No such file or directory"
+  - "exec: \"docker-compose\": executable file not found in $PATH"
+  - "OCI runtime exec failed: exec: \"docker-compose\": executable file not found"
+root_cause: |
+  The standalone `docker-compose` v1 binary (Python-based) was removed from GitHub-hosted
+  ubuntu-22.04 and ubuntu-24.04 runner images. Only the Docker Compose v2 plugin is
+  available, invoked as `docker compose` (space, not hyphen) as a Docker CLI subcommand.
+
+  The docker-compose v1 project reached end-of-life in July 2023. GitHub Actions runner
+  images on ubuntu-22.04 removed it during the ubuntu-22.04 image update cycle. Ubuntu 24.04
+  runners never included v1.
+
+  Workflows that use `docker-compose up`, `docker-compose build`, `docker-compose down`, or
+  any `docker-compose` subcommand with the hyphenated binary name will fail immediately with
+  "command not found". This often surfaces in scripts that run in `run:` steps or in shell
+  scripts checked into the repo.
+
+  The Docker Compose v2 plugin (`docker compose`) is a drop-in replacement for most
+  workflows, but it is invoked differently and has subtle behavior differences around
+  compatibility modes, exit codes on dependent service failures, and environment variable
+  interpolation.
+fix: |
+  Replace all calls to `docker-compose` (hyphen) with `docker compose` (space). The v2
+  plugin is pre-installed on all current GitHub-hosted runners as a Docker CLI plugin.
+  If you need to support both old and new syntax in scripts, add a shell alias or wrapper.
+fix_code:
+  - language: yaml
+    label: "Replace docker-compose (v1) with docker compose (v2)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ v1 syntax — docker-compose binary no longer exists
+            # - run: docker-compose up -d
+            # - run: docker-compose build
+            # - run: docker-compose down
+
+            # ✅ v2 syntax — docker compose plugin (pre-installed)
+            - name: Start services
+              run: docker compose up -d
+
+            - name: Run tests
+              run: docker compose run --rm app npm test
+
+            - name: Teardown
+              run: docker compose down --volumes
+  - language: yaml
+    label: "Script-based fallback for repos with shell scripts using old syntax"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # Create a shim so legacy scripts work without editing every file
+            - name: Create docker-compose shim
+              run: |
+                sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose \
+                  /usr/local/bin/docker-compose
+            - run: ./scripts/integration-test.sh
+prevention:
+  - "Audit all workflow files and shell scripts for `docker-compose` (hyphen) and replace with `docker compose` (space)"
+  - "Pin `docker compose version` in a setup step to document the expected Compose version"
+  - "When migrating repos, search for the pattern in Makefiles, shell scripts, and docker-compose.yml files — not just .github/workflows/"
+  - "The v2 plugin is at /usr/libexec/docker/cli-plugins/docker-compose if a shim is needed for legacy scripts"
+docs:
+  - url: "https://docs.docker.com/compose/migrate/"
+    label: "Docker Docs: Migrate to Compose v2"
+  - url: "https://github.com/docker/compose/releases/tag/v2.0.0"
+    label: "Docker Compose v2.0.0 release (GA plugin replacing standalone binary)"
+  - url: "https://github.com/actions/runner-images/issues/6325"
+    label: "runner-images GitHub Issue: docker-compose v1 removal from ubuntu-22.04"

package/errors/runner-environment/ubuntu-24-gcc-default-version-upgrade.yml

@@ -0,0 +1,113 @@
+id: runner-environment-127
+title: "ubuntu-24.04 Runner: GCC 13 Default Breaks Workflows Hardcoding gcc-12 or gcc-11"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - gcc
+  - compiler
+  - c-cpp
+  - breaking-change
+  - runner-image
+patterns:
+  - regex: 'gcc-1[012]:\s*(command not found|not found)'
+    flags: 'i'
+  - regex: '/usr/bin/gcc-1[012]:\s*No such file or directory'
+    flags: 'i'
+  - regex: 'update-alternatives.*gcc.*no alternatives'
+    flags: 'i'
+  - regex: 'gcc: error: unrecognized command-line option.*std=c\+\+20'
+    flags: 'i'
+error_messages:
+  - "gcc-12: command not found"
+  - "gcc-11: command not found"
+  - "/usr/bin/gcc-12: No such file or directory"
+  - "g++-12: command not found"
+  - "cc1plus: error: unrecognized command line option"
+root_cause: |
+  Ubuntu 24.04 (Noble Numbat) ships GCC 13 as its default and only pre-installed compiler
+  version. The ubuntu-24.04 GitHub-hosted runner image follows this: `gcc` and `g++` point
+  to GCC 13, and older versions (`gcc-12`, `gcc-11`, `gcc-10`) are not installed by default.
+
+  Workflows that hardcode a specific compiler version — `gcc-12`, `g++-12`, `gcc-11`, or
+  set `CC=gcc-12` / `CXX=g++-12` in environment variables — will fail immediately with
+  "command not found" when the runner image is ubuntu-24.04.
+
+  This commonly breaks:
+  - C/C++ projects that pin a specific GCC version for ABI stability or reproducibility
+  - CMake projects with `CMAKE_C_COMPILER=gcc-12` in toolchain files or workflow env vars
+  - Projects testing against specific GCC versions using a matrix
+  - Makefile-based builds with `CC := gcc-12` hard-coded
+
+  GCC 13 has improved standards compliance, stricter warnings-as-errors behavior, and
+  changed default `-std` values for C and C++. Code that compiled cleanly on GCC 12 may
+  emit new warnings or errors on GCC 13 even after installing the right package.
+fix: |
+  Update compiler references to use GCC 13 on ubuntu-24.04, or install the specific GCC
+  version needed via apt before building. For multi-version testing, use a runner matrix
+  pairing the Ubuntu version with the GCC version.
+fix_code:
+  - language: yaml
+    label: "Update to GCC 13 on ubuntu-24.04 or install older version"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ GCC 12 not pre-installed on ubuntu-24.04
+            # env:
+            #   CC: gcc-12
+            #   CXX: g++-12
+
+            # ✅ Option 1: use the default GCC 13 on ubuntu-24.04
+            - name: Build with GCC 13 (default on ubuntu-24.04)
+              env:
+                CC: gcc
+                CXX: g++
+              run: make -j$(nproc)
+
+            # ✅ Option 2: install a specific GCC version
+            - name: Install GCC 12
+              run: sudo apt-get install -y gcc-12 g++-12
+
+            - name: Build with GCC 12
+              env:
+                CC: gcc-12
+                CXX: g++-12
+              run: make -j$(nproc)
+  - language: yaml
+    label: "Matrix strategy to test multiple GCC versions across Ubuntu versions"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-22.04
+                  gcc: '12'
+                - os: ubuntu-24.04
+                  gcc: '13'
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install GCC ${{ matrix.gcc }}
+              run: sudo apt-get install -y gcc-${{ matrix.gcc }} g++-${{ matrix.gcc }}
+            - name: Build
+              env:
+                CC: gcc-${{ matrix.gcc }}
+                CXX: g++-${{ matrix.gcc }}
+              run: make -j$(nproc)
+prevention:
+  - "Avoid hardcoding specific GCC versions (`gcc-12`, `gcc-11`) in workflow env vars — use the default `gcc` and pin the Ubuntu version instead"
+  - "When upgrading to ubuntu-24.04, audit all `CC=`, `CXX=`, `CMAKE_C_COMPILER=`, and `CMAKE_CXX_COMPILER=` references in workflows and CMakeLists.txt"
+  - "Use a matrix to explicitly pair OS version with GCC version to make the GCC dependency visible and testable"
+  - "GCC 13 introduced stricter warnings for C23 and C++23 features — review `-Werror` builds carefully after upgrading"
+docs:
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image README (installed compilers section)"
+  - url: "https://gcc.gnu.org/gcc-13/changes.html"
+    label: "GCC 13 release notes — breaking changes from GCC 12"
+  - url: "https://packages.ubuntu.com/noble/gcc"
+    label: "Ubuntu 24.04 Noble: gcc package (default version 13)"

package/errors/runner-environment/ubuntu-24-netstat-net-tools-not-installed.yml

@@ -0,0 +1,99 @@
+id: runner-environment-126
+title: "ubuntu-24.04 Runner: netstat / ifconfig Not Pre-installed (net-tools Removed)"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - netstat
+  - net-tools
+  - ifconfig
+  - network-diagnostics
+  - breaking-change
+patterns:
+  - regex: 'netstat:\s*(command not found|not found)'
+    flags: 'i'
+  - regex: 'ifconfig:\s*(command not found|not found)'
+    flags: 'i'
+  - regex: '/usr/bin/netstat:\s*No such file or directory'
+    flags: 'i'
+  - regex: 'net-tools.*not installed'
+    flags: 'i'
+error_messages:
+  - "netstat: command not found"
+  - "ifconfig: command not found"
+  - "/usr/bin/netstat: No such file or directory"
+  - "bash: netstat: command not found"
+  - "sh: 1: netstat: not found"
+root_cause: |
+  The `net-tools` package — which provides `netstat`, `ifconfig`, `arp`, `route`, and
+  `nameif` — is not pre-installed on ubuntu-24.04 GitHub-hosted runner images. Ubuntu 24.04
+  (Noble Numbat) removed `net-tools` from its default package set, replacing these legacy
+  utilities with modern equivalents from the `iproute2` suite (`ss`, `ip`, `ip route`).
+
+  Ubuntu 22.04 runner images also do not guarantee `net-tools` is installed by default.
+  CI scripts that use `netstat -tlnp` to check which ports are listening, `ifconfig` to
+  inspect network interfaces, or `route -n` to check routing tables will fail immediately
+  with "command not found" on modern runner images.
+
+  This commonly appears in:
+  - Wait-for-port scripts that poll `netstat -tlnp | grep :8080`
+  - Service health check scripts using `netstat` to verify a database port is open
+  - Network diagnostics in CI debug steps
+  - Shell scripts copied from older Linux documentation that assume `net-tools` is present
+fix: |
+  Replace `net-tools` commands with their `iproute2` equivalents, which are pre-installed
+  on all ubuntu runners. Alternatively, install `net-tools` via apt before using it.
+fix_code:
+  - language: yaml
+    label: "Replace net-tools commands with iproute2 equivalents"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ net-tools commands — not pre-installed on ubuntu-24.04
+            # - run: netstat -tlnp | grep :5432
+            # - run: ifconfig eth0
+            # - run: route -n
+
+            # ✅ iproute2 equivalents — pre-installed on all ubuntu runners
+            - name: Check listening ports
+              run: ss -tlnp | grep :5432    # replaces: netstat -tlnp | grep :5432
+
+            - name: Inspect network interface
+              run: ip addr show eth0         # replaces: ifconfig eth0
+
+            - name: Check routing table
+              run: ip route show             # replaces: route -n
+  - language: yaml
+    label: "Install net-tools if migrating scripts is not feasible"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install net-tools (legacy compatibility)
+              run: sudo apt-get install -y --no-install-recommends net-tools
+
+            - name: Wait for database port
+              run: |
+                for i in $(seq 1 30); do
+                  netstat -tlnp | grep -q :5432 && break
+                  sleep 1
+                done
+prevention:
+  - "Prefer `ss` over `netstat` and `ip addr` over `ifconfig` in all new CI scripts — they are pre-installed on every ubuntu runner"
+  - "Audit shell scripts checked into the repo for `netstat`, `ifconfig`, `arp`, and `route` commands before upgrading runners to ubuntu-24.04"
+  - "For wait-for-port patterns, consider using `nc -z localhost PORT` or `/dev/tcp/localhost/PORT` instead of polling netstat"
+  - "`ss -tlnp` is functionally identical to `netstat -tlnp` for port-checking — it is a direct substitute"
+docs:
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image installed software README"
+  - url: "https://manpages.ubuntu.com/manpages/noble/man8/ss.8.html"
+    label: "Ubuntu 24.04 manpage: ss (replaces netstat)"
+  - url: "https://wiki.ubuntu.com/FocalFossa/ReleaseNotes#net-tools_Removal"
+    label: "Ubuntu release notes: net-tools deprecation in favor of iproute2"

package/errors/runner-environment/ubuntu-apt-key-deprecated-no-pubkey.yml

@@ -0,0 +1,110 @@
+id: runner-environment-128
+title: "ubuntu-22.04/24.04: apt-key Deprecated — Third-Party Repo Keys Cause NO_PUBKEY Errors"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-22
+  - ubuntu-24
+  - apt
+  - apt-key
+  - gpg
+  - package-signing
+  - third-party-repo
+patterns:
+  - regex: 'apt-key\s+is\s+deprecated'
+    flags: 'i'
+  - regex: 'NO_PUBKEY\s+[0-9A-F]{16}'
+    flags: 'i'
+  - regex: 'W:\s*Key\s+is\s+stored\s+in\s+legacy\s+trusted\.gpg\s+keyring'
+    flags: 'i'
+  - regex: 'The following signatures couldn''t be verified because the public key is not available'
+    flags: 'i'
+error_messages:
+  - "W: apt-key is deprecated. Manage keyring files in trusted.gpg.d instead (see apt-key(8))."
+  - "W: Key is stored in legacy trusted.gpg keyring (/etc/apt/trusted.gpg), see the DEPRECATION section in apt-key(8) for details."
+  - "The following signatures couldn't be verified because the public key is not available: NO_PUBKEY A1715D88E1DF1F24"
+  - "W: http://ppa.launchpad.net/...: NO_PUBKEY"
+  - "GPG error: ... NO_PUBKEY"
+root_cause: |
+  `apt-key` was deprecated in Ubuntu 22.04 and is scheduled for removal in future Ubuntu
+  versions. On ubuntu-22.04 and ubuntu-24.04 GitHub-hosted runner images, workflows that
+  add third-party repository GPG keys using `apt-key add -` or `apt-key adv --keyserver`
+  emit deprecation warnings and, in some configurations, fail to authenticate packages.
+
+  The old method stored keys in `/etc/apt/trusted.gpg` — a global keyring trusted for ALL
+  repositories. Ubuntu 22.04 began phasing this out in favor of per-repository keyrings
+  stored as `.gpg` files under `/usr/share/keyrings/`, referenced via `signed-by=` in
+  the sources list entry.
+
+  Common symptoms:
+  - `apt-get update` emits "NO_PUBKEY" warnings followed by package authentication failures
+  - Installing packages from third-party PPAs (e.g., Google Chrome, Hashicorp, NodeSource)
+    fails with "The following packages cannot be authenticated"
+  - Steps that use `add-apt-repository ppa:...` work on ubuntu-20.04 but produce warnings
+    or fail on ubuntu-22.04/24.04
+
+  Workflows that pipe curl output directly into `apt-key add -` (a historically common
+  pattern in CI setup scripts) will produce warnings on ubuntu-22.04 and may fail silently
+  on ubuntu-24.04 if the key is not recognized by the new keyring mechanism.
+fix: |
+  Replace `apt-key add` with the modern pattern: download the GPG key as a dearmored `.gpg`
+  file into `/usr/share/keyrings/`, then reference it with `signed-by=` in the apt sources
+  list entry. This is the Ubuntu 22.04+ recommended approach.
+fix_code:
+  - language: yaml
+    label: "Old pattern (deprecated) vs new signed-by pattern"
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ Deprecated: apt-key add — produces warnings on 22.04, may fail on 24.04
+            # - name: Add Hashicorp repo (old way)
+            #   run: |
+            #     curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
+            #     sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
+
+            # ✅ Modern pattern: signed-by= with per-repo keyring file
+            - name: Add Hashicorp repo (modern way)
+              run: |
+                curl -fsSL https://apt.releases.hashicorp.com/gpg \
+                  | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
+                echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
+                  https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
+                  | sudo tee /etc/apt/sources.list.d/hashicorp.list
+
+            - name: Install Terraform
+              run: |
+                sudo apt-get update
+                sudo apt-get install -y terraform
+  - language: yaml
+    label: "NodeSource / NVM repo setup using modern keyring pattern"
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # Modern NodeSource setup (replaces legacy curl | bash installer)
+            - name: Add NodeSource repo
+              run: |
+                curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
+                  | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg
+                echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] \
+                  https://deb.nodesource.com/node_20.x nodistro main" \
+                  | sudo tee /etc/apt/sources.list.d/nodesource.list
+            - run: sudo apt-get update && sudo apt-get install -y nodejs
+prevention:
+  - "Replace all `apt-key add -` calls with the `gpg --dearmor` + `signed-by=` pattern — it works on ubuntu-20.04 through ubuntu-24.04"
+  - "Third-party vendors (Hashicorp, Google, Microsoft, NodeSource) have updated their installation docs to use the modern pattern — follow vendor docs rather than old blog posts"
+  - "For PPA repositories, use `add-apt-repository --no-update` with the modern key format, or switch to the vendor's official deb repo"
+  - "Audit CI scripts for `curl ... | apt-key add -` pipelines — these are the most common source of this error"
+docs:
+  - url: "https://manpages.ubuntu.com/manpages/jammy/man8/apt-key.8.html"
+    label: "Ubuntu apt-key(8) manpage — DEPRECATION section"
+  - url: "https://wiki.debian.org/DebianRepository/UseThirdParty"
+    label: "Debian Wiki: Using Third-Party Repositories (modern signed-by pattern)"
+  - url: "https://github.com/actions/runner-images/issues/7213"
+    label: "runner-images GitHub Issue: apt-key deprecation warnings on ubuntu-22.04"

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

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

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

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

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

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

package/package.json

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