@htekdev/actions-debugger 1.0.86 → 1.0.88

package/errors/known-unsolved/known-unsolved-051.yml

@@ -0,0 +1,94 @@
+id: known-unsolved-051
+title: 'No workflow-level `timeout-minutes` — only job-level and step-level timeouts; runaway workflows consume runner hours with no global cap'
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout
+  - workflow-level
+  - runner-hours
+  - billing
+  - limitation
+  - runaway-workflow
+patterns:
+  - regex: 'timeout.minutes'
+    flags: 'i'
+  - regex: 'workflow.*timed? ?out|timed? ?out.*workflow'
+    flags: 'i'
+error_messages:
+  - "No workflow-level timeout — only job-level timeout-minutes is supported"
+  - "Unexpected key 'timeout-minutes' at workflow level — property is only valid on jobs"
+root_cause: |
+  GitHub Actions supports `timeout-minutes:` only at the JOB level and STEP level.
+  There is no `timeout-minutes:` field at the workflow level (the level containing
+  `on:`, `env:`, and `jobs:`). If placed at the workflow level, actionlint reports
+  "unexpected key 'timeout-minutes'" and the key is silently ignored at runtime
+  with no effect on execution.
+
+  The default job timeout is 360 minutes (6 hours). A workflow with multiple jobs,
+  each using the default timeout, can run for many times 360 minutes total. There is
+  no built-in way to enforce a global "if this entire workflow hasn't finished in X
+  hours, cancel everything."
+
+  Common scenarios where this causes unexpected runner hour consumption:
+  - A self-hosted runner goes offline mid-job; the job hangs until its per-job timeout
+  - A workflow waiting on a deployment environment review that is never approved
+  - A matrix job with a misconfigured container that hangs on startup
+  - A network call in a step that never times out (no step-level timeout set)
+
+  This is a long-requested GitHub Actions feature with hundreds of community upvotes.
+fix: |
+  Workarounds (no official workflow-level timeout exists):
+
+  1. SET CONSERVATIVE JOB TIMEOUTS: Add explicit `timeout-minutes:` to every job
+     with a value appropriate for that job's actual expected runtime plus a buffer.
+     Do not rely on the 360-minute default.
+
+  2. SET STEP-LEVEL TIMEOUTS: Add `timeout-minutes:` to individual steps that perform
+     network calls, long-running builds, or any operation that can hang.
+
+  3. WATCHDOG WORKFLOW: A separate workflow triggered by `workflow_run` can monitor
+     in-progress runs and cancel them via the API if they exceed a threshold duration.
+
+  4. ENVIRONMENT REVIEW EXPIRY: For deployment workflows stuck on required reviewers,
+     configure an expiry window under Settings > Environments > [env] >
+     Deployment protection rules > Timeout.
+fix_code:
+  - language: yaml
+    label: 'Set explicit per-job timeouts as a workaround'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 15   # Set per-job: build should not exceed 15 min
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          timeout-minutes: 20   # Integration tests: 20 min max
+          steps:
+            - name: Run tests
+              timeout-minutes: 15   # Step-level: individual test run cap
+              run: npm run test:integration
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          timeout-minutes: 10   # Deployment itself should be fast
+          environment: production
+          steps:
+            - run: ./scripts/deploy.sh
+prevention:
+  - 'Always set `timeout-minutes:` on every job — do not rely on the 360-minute default for normal CI workflows.'
+  - 'Add `timeout-minutes:` to individual steps that perform network I/O, external API calls, or any blocking operation.'
+  - 'Monitor unexpected Actions billing spikes: they often indicate a stuck workflow running against the 6-hour default job timeout.'
+  - 'Set deployment environment review expiry windows to prevent workflows from hanging indefinitely awaiting approval.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'Workflow syntax: jobs.<job_id>.timeout-minutes'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes'
+    label: 'Workflow syntax: jobs.<job_id>.steps[*].timeout-minutes'
+  - url: 'https://github.com/orgs/community/discussions/16058'
+    label: 'GitHub Community: Workflow-level timeout-minutes (feature request)'

package/errors/runner-environment/macos-arm64-rosetta-not-installed.yml

@@ -0,0 +1,97 @@
+id: runner-environment-154
+title: "macOS ARM64 runner: Rosetta 2 not pre-installed — x86_64 binaries fail"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - arm64
+  - rosetta
+  - apple-silicon
+  - binary-compatibility
+patterns:
+  - regex: 'Bad CPU type in executable'
+    flags: i
+  - regex: 'Exec format error'
+    flags: i
+  - regex: 'is not supported on this machine \(CPU type'
+    flags: i
+  - regex: 'rosetta.*not.*install|softwareupdate.*rosetta'
+    flags: i
+error_messages:
+  - "zsh: bad CPU type in executable: /usr/local/bin/mytool"
+  - "Exec format error"
+  - "/usr/local/bin/node: Bad CPU type in executable"
+  - "The file '/path/to/binary' is not supported on this machine (CPU type 16777223)"
+root_cause: |
+  GitHub-hosted macOS runners on Apple Silicon hardware (macos-14, macos-15, and the `macos-latest`
+  label when pointing to ARM64 images) do NOT have Rosetta 2 pre-installed. Rosetta 2 is Apple's
+  x86_64-to-ARM64 translation layer that allows Intel-compiled binaries to run on Apple Silicon.
+
+  Without Rosetta 2, any x86_64 binary executed on the ARM64 runner fails immediately with
+  "Bad CPU type in executable" or "Exec format error". Common sources of x86_64 binaries:
+  - Pre-compiled tool downloads targeting darwin-x64
+  - npm packages with native addons built for x86_64
+  - Homebrew formulae that only have x86_64 bottles
+  - Custom build scripts that hardcode `arch -x86_64`
+  - Docker images using `linux/amd64` platform
+
+  This is distinct from Linux ARM64 runners (ubuntu-24.04-arm) where the error manifests
+  differently and no Rosetta equivalent exists. On macOS, Rosetta 2 can be installed as a
+  one-time setup step.
+fix: |
+  Option 1 — Install Rosetta 2 at job start (quick workaround):
+  Add `softwareupdate --install-rosetta --agree-to-license` as the first step. This allows
+  x86_64 binaries to run via translation.
+
+  Option 2 — Use ARM64-native binaries (preferred):
+  Update download scripts to detect `arch` and fetch the correct binary:
+  - Use `$(uname -m)` to branch between arm64 and x86_64 download URLs
+  - Use `arch -arm64 brew install` for Homebrew packages
+  - For npm: ensure native addons are rebuilt for the current architecture
+
+  Option 3 — Pin to Intel macOS runner:
+  Use `runs-on: macos-13` which is the last Intel-based macOS runner image. Note that
+  macos-13 is scheduled for deprecation; this is a temporary workaround only.
+fix_code:
+  - language: yaml
+    label: "Install Rosetta 2 as first step (workaround)"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest  # ARM64 Apple Silicon
+          steps:
+            - name: Install Rosetta 2
+              run: softwareupdate --install-rosetta --agree-to-license
+            - uses: actions/checkout@v4
+            - name: Download tool
+              run: |
+                # x86_64 binary will now work via Rosetta translation
+                curl -L https://example.com/tool-darwin-x64 -o tool
+                chmod +x tool
+                ./tool
+  - language: yaml
+    label: "Detect architecture and fetch the correct binary (preferred)"
+    code: |
+      steps:
+        - name: Download architecture-appropriate binary
+          run: |
+            ARCH=$(uname -m)
+            if [ "$ARCH" = "arm64" ]; then
+              BINARY_URL="https://example.com/tool-darwin-arm64"
+            else
+              BINARY_URL="https://example.com/tool-darwin-x64"
+            fi
+            curl -L "$BINARY_URL" -o tool
+            chmod +x tool
+            ./tool
+prevention:
+  - "Always test workflows on both `macos-13` (Intel) and `macos-14`+ (ARM64) runners"
+  - "Check download scripts for hardcoded `darwin-x64` or `darwin-amd64` architecture strings"
+  - "Prefer tools distributed via Homebrew — many formulae now have native ARM64 bottles"
+  - "Use `${{ runner.arch }}` in workflow expressions to branch on architecture (`X64` vs `ARM64`)"
+  - "Audit npm packages with native addons — they must support `darwin-arm64` or provide a WASM fallback"
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs: Supported runners and hardware resources"
+  - url: "https://support.apple.com/en-us/102527"
+    label: "Apple: If you need to install Rosetta on your Mac"

package/errors/runner-environment/runner-disk-full-no-space-left.yml

@@ -0,0 +1,106 @@
+id: runner-environment-155
+title: "GitHub-hosted runner disk full — 'No space left on device' during large builds"
+category: runner-environment
+severity: error
+tags:
+  - disk-space
+  - ubuntu
+  - docker
+  - large-builds
+  - runner-storage
+patterns:
+  - regex: 'No space left on device'
+    flags: i
+  - regex: 'write.*error.*28|errno 28'
+    flags: i
+  - regex: 'disk.*full|filesystem.*full|out of disk'
+    flags: i
+  - regex: 'no space left'
+    flags: i
+error_messages:
+  - "No space left on device"
+  - "Error: write /var/lib/docker/tmp/...: no space left on device"
+  - "tar: ./app: Cannot write: No space left on device"
+  - "error: failed to push some refs: No space left on device"
+  - "OSError: [Errno 28] No space left on device"
+root_cause: |
+  GitHub-hosted Ubuntu runners have approximately 14 GB of usable disk space after the
+  pre-installed tool suite occupies the rest. The runner image includes a large set of
+  pre-installed software that consumes the majority of available disk:
+  - Android SDK: ~8.7 GB
+  - .NET SDKs: ~1.5 GB
+  - Haskell/GHC: ~5.4 GB
+  - CodeQL: ~5.4 GB
+  - Docker images cached on the runner: varies
+
+  Workflows that perform large Docker builds, pull multiple Docker images, build large
+  native packages, or accumulate many npm/cargo/maven dependencies can exhaust the
+  ~14 GB limit. Common triggers:
+  - `docker build` for large multi-stage images
+  - `docker pull` of several large base images
+  - Building and caching large Rust/C++ projects
+  - Downloading large ML models or datasets
+  - Generating large test fixtures or build artifacts
+
+  The error manifests in diverse ways: Docker build errors (errno 28), tar extraction
+  failures, git push failures writing pack files, or Python/Node crashes writing temp files.
+fix: |
+  Free disk space before your build by removing pre-installed tools you don't need.
+  The community-maintained `jlumbroso/free-disk-space` action is the standard solution.
+
+  Manual removal commands for the largest consumers:
+  - Android SDK: `sudo rm -rf /usr/local/lib/android`
+  - .NET: `sudo rm -rf /usr/share/dotnet`
+  - Haskell/GHC: `sudo rm -rf /usr/local/.ghcup`
+  - Large packages: `sudo apt-get clean && sudo apt-get autoremove -y`
+  - Docker build cache: `docker builder prune -af`
+
+  Alternatively, upgrade to GitHub-hosted larger runners (4+ cores) which provide
+  more disk space, or use self-hosted runners.
+fix_code:
+  - language: yaml
+    label: "Free disk space before large Docker build"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Free disk space
+              uses: jlumbroso/free-disk-space@main
+              with:
+                tool-cache: false
+                android: true
+                dotnet: true
+                haskell: true
+                large-packages: true
+                docker-images: true
+                swap-storage: true
+            - uses: actions/checkout@v4
+            - name: Build Docker image
+              run: docker build -t myapp:latest .
+  - language: yaml
+    label: "Manual removal of largest pre-installed tools"
+    code: |
+      steps:
+        - name: Free disk space (manual)
+          run: |
+            df -h /
+            sudo rm -rf /usr/local/lib/android
+            sudo rm -rf /usr/share/dotnet
+            sudo rm -rf /usr/local/.ghcup
+            sudo apt-get clean
+            docker builder prune -af || true
+            df -h /
+prevention:
+  - "Add a disk-space check step (`df -h /`) early in the workflow to detect capacity issues before they cause cryptic failures"
+  - "Run `jlumbroso/free-disk-space` before any Docker build or large compilation job"
+  - "Remove only tools you know you don't need — removing the tool-cache may break `actions/setup-*` steps"
+  - "Consider using `runs-on: ubuntu-latest-4-cores` (GitHub Teams) which provides more disk space"
+  - "Use Docker `--no-cache` flags cautiously — reusing layer cache can actually save disk vs rebuilding every layer"
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs: Runner hardware resources"
+  - url: "https://github.com/jlumbroso/free-disk-space"
+    label: "jlumbroso/free-disk-space action"
+  - url: "https://github.com/actions/runner-images/issues/2840"
+    label: "runner-images#2840: Tracking disk space usage"

package/errors/runner-environment/runner-environment-151.yml

@@ -0,0 +1,93 @@
+id: runner-environment-151
+title: "Docker container action creates root-owned files causing Permission denied in following steps"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - container-action
+  - file-permissions
+  - root-user
+  - workspace
+patterns:
+  - regex: 'Permission denied'
+    flags: i
+  - regex: 'EACCES: permission denied'
+    flags: i
+  - regex: 'cannot open .+ Permission denied'
+    flags: i
+  - regex: 'error: open .+ permission denied'
+    flags: i
+error_messages:
+  - "Permission denied"
+  - "cannot create directory '...': Permission denied"
+  - "EACCES: permission denied, open '/github/workspace/...'"
+  - "error: cannot open '.git/COMMIT_EDITMSG': Permission denied"
+  - "chown: changing ownership of '...': Operation not permitted"
+root_cause: |
+  Docker-based GitHub Actions — both `uses: docker://image:tag` inline steps and
+  actions with `runs.using: docker` in their action.yml — run their container process
+  as root (UID 0) by default unless the Dockerfile explicitly sets a USER directive.
+
+  Any files written to `GITHUB_WORKSPACE` (mounted at `/github/workspace` inside the
+  container) are created with root ownership (uid=0, gid=0). Subsequent workflow steps
+  run as the `runner` user (UID 1001) and cannot read, modify, or delete root-owned
+  files, causing "Permission denied" errors.
+
+  The failure is especially common when:
+  - A Docker action writes build artifacts, generated code, or lock files.
+  - A subsequent step tries to commit changes or run tools on the generated output.
+  - The workflow uses `actions/checkout` after a Docker action and git operations fail.
+fix: |
+  Option 1 — Chown the workspace after the Docker action (easiest for third-party actions):
+    Add a step after the Docker action: `sudo chown -R "$USER:$(id -gn)" "$GITHUB_WORKSPACE"`
+
+  Option 2 — Set USER in the Dockerfile (best for actions you control):
+    Add `USER 1001` (runner UID) to the action's Dockerfile so all written files
+    are owned by the runner user.
+
+  Option 3 — Use --user flag in the Docker run args:
+    Set `args` in the action's action.yml to include `--user=1001:127`.
+fix_code:
+  - language: yaml
+    label: "Fix: chown workspace after Docker action (works for any Docker-based action)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Run Docker-based action
+          uses: docker://my-build-image:latest
+          with:
+            args: '--output /github/workspace/dist'
+
+        - name: Fix file ownership after Docker action
+          run: sudo chown -R "$USER:$(id -gn)" "$GITHUB_WORKSPACE"
+
+        - name: Use build output (now accessible as runner user)
+          run: ls -la dist/ && cat dist/output.txt
+  - language: yaml
+    label: "Fix: set non-root USER in Dockerfile (preferred when controlling the action)"
+    code: |
+      # In your Docker action's Dockerfile — run as UID 1001 to match GitHub runner
+      # FROM ubuntu:22.04
+      # RUN useradd -u 1001 -g 127 runner
+      # WORKDIR /github/workspace
+      # USER 1001
+      # ENTRYPOINT ["/entrypoint.sh"]
+      
+      # With this Dockerfile, no chown step is needed — files are owned by runner user
+      steps:
+        - uses: actions/checkout@v4
+        - uses: ./  # local Docker action with non-root USER
+        - run: cat generated-output.txt  # accessible without permission errors
+prevention:
+  - "Always set a non-root USER directive in Dockerfiles for actions that write to the workspace."
+  - "After any third-party Docker action, add a chown step before accessing created files."
+  - "Prefer JavaScript/TypeScript or composite actions over Docker actions when workspace I/O is needed — they run as the runner user by default."
+  - "Test Docker actions locally with UID 1001 to catch permission issues before CI."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/dockerfile-support-for-github-actions"
+    label: "Dockerfile support for GitHub Actions"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action"
+    label: "Creating a Docker container action"
+  - 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"

package/errors/runner-environment/runner-environment-152.yml

@@ -0,0 +1,90 @@
+id: runner-environment-152
+title: 'Organization "Require immutable actions" policy blocks tag-pinned action refs — must use full commit SHA'
+category: runner-environment
+severity: error
+tags:
+  - immutable-actions
+  - sha-pinning
+  - security-policy
+  - organization-policy
+  - enterprise
+  - supply-chain
+patterns:
+  - regex: 'not pinned to an immutable SHA'
+    flags: 'i'
+  - regex: 'Action.*is not pinned.*immutable'
+    flags: 'i'
+  - regex: 'immutable actions.*required'
+    flags: 'i'
+  - regex: 'Update the workflow to use the immutable reference'
+    flags: 'i'
+error_messages:
+  - "Error: Action 'actions/checkout@v4' is not pinned to an immutable SHA. Update the workflow to use the immutable reference."
+  - "Actions must be pinned to an immutable commit SHA. Organization policy requires immutable actions."
+  - "Error: This action reference is not immutable. The organization requires all actions to be pinned by SHA."
+root_cause: |
+  GitHub introduced an organization-level security policy called "Require immutable
+  actions" (available in GitHub Enterprise and GitHub Teams since late 2025). When
+  enabled by an organization admin, every `uses:` reference in every workflow within
+  that organization must point to a full commit SHA rather than a mutable tag (such
+  as `@v4`) or branch name (such as `@main`).
+
+  Tags and branches are mutable — they can be updated to point to a different commit
+  at any time. An attacker who compromises an upstream action repository can move a
+  widely used tag to point to malicious code. The SHA immutability policy protects
+  against this supply-chain attack vector by ensuring the exact code being run is
+  pinned and verifiable.
+
+  When the policy is active, the Actions runner validates every `uses:` reference
+  before execution and refuses to run any workflow containing mutable refs, even if
+  the referenced tag currently points to a trusted commit. This commonly surfaces
+  after an organization adopts the policy post-hoc, breaking all existing workflows.
+fix: |
+  Replace every `uses:` tag or branch reference with the full 40-character commit SHA.
+  Add the human-readable tag as an inline comment for maintainability.
+
+  To find the SHA for a specific action version:
+  - Visit the action's GitHub releases page (e.g., github.com/actions/checkout/releases/tag/v4)
+  - Click the commit SHA link next to the tag
+
+  Tools that automate SHA pinning across all workflow files:
+  - `ratchet` (github.com/thepwagner/ratchet): `ratchet pin .github/workflows/`
+  - `pin-github-action` (Mend): available as a GitHub Action or CLI
+  - Dependabot with `package-ecosystem: github-actions` maintains pinned SHAs automatically
+fix_code:
+  - language: yaml
+    label: 'Pin action refs to full commit SHA (with readable comment)'
+    code: |
+      # BEFORE (fails with immutable actions org policy)
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+        - uses: actions/upload-artifact@v4
+
+      # AFTER (SHA-pinned with human-readable tag comment)
+      steps:
+        - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+  - language: yaml
+    label: 'Dependabot config to keep SHA pins up to date automatically'
+    code: |
+      # .github/dependabot.yml
+      version: 2
+      updates:
+        - package-ecosystem: github-actions
+          directory: /
+          schedule:
+            interval: weekly
+prevention:
+  - 'Audit all workflow files before enabling the org policy — run ratchet or pin-github-action across the entire .github/workflows/ directory first.'
+  - 'Enable the policy in a single pilot repository before rolling it out organization-wide to identify and fix all mutable refs.'
+  - 'Add actionlint with SHA-pinning rules to CI so new mutable refs are caught in PRs before reaching main.'
+  - 'Configure Dependabot for github-actions to automatically open PRs whenever a pinned SHA has a new upstream release.'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions'
+    label: 'Security hardening for GitHub Actions: using third-party actions'
+  - url: 'https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization'
+    label: 'Requiring immutable action components (org policy settings)'
+  - url: 'https://github.com/thepwagner/ratchet'
+    label: 'ratchet — CLI tool to pin GitHub Actions refs to SHA'

package/errors/runner-environment/ubuntu-snap-snapd-not-running.yml

@@ -0,0 +1,90 @@
+id: runner-environment-156
+title: "ubuntu runner: snap packages unavailable — snapd not running"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - snap
+  - snapd
+  - packages
+  - ubuntu-24
+patterns:
+  - regex: 'cannot communicate with server.*snapd\.socket'
+    flags: i
+  - regex: 'snapd is not running'
+    flags: i
+  - regex: 'snap.*connect.*refused|dial unix.*snapd'
+    flags: i
+  - regex: 'snap: command not found'
+    flags: i
+error_messages:
+  - "error: cannot communicate with server: Post \"http://localhost/v2/snaps/kubectl\": dial unix /run/snapd.socket: connect: no such file or directory"
+  - "error: cannot communicate with server: Post http://localhost/v2/snaps: dial unix /run/snapd.socket: connect: no such file or directory"
+  - "snapd is not running"
+  - "snap: command not found"
+root_cause: |
+  GitHub-hosted Ubuntu runners do not run the snapd daemon. The snap socket
+  `/run/snapd.socket` is never created, so any `snap install` command immediately fails
+  when attempting to communicate with the snap store daemon.
+
+  While the `snap` binary may be present on the runner image, the background snapd service
+  is not started because GitHub-hosted runners use a minimal systemd-free environment.
+  Starting snapd manually is not practical — it requires systemd or a complex manual
+  daemon startup sequence, and snap packages are confined using AppArmor profiles that
+  may also be unavailable in the runner environment.
+
+  This is frequently encountered when workflows try to install tools distributed as snaps:
+  kubectl, microk8s, aws-cli, spotify, and many developer utilities.
+fix: |
+  Replace `snap install` with an alternative package source for the tool you need:
+
+  - **kubectl**: Use `curl -LO https://dl.k8s.io/release/...` or the `azure/setup-kubectl` action
+  - **aws-cli v2**: Use `pip install awscli` or the official AWS install script via apt
+  - **Helm**: Use the `azure/setup-helm` action or the official install script
+  - **General tools**: Check for apt, pip, npm, or GitHub releases as alternatives
+
+  If you must install a snap, consider using a self-hosted runner with snapd enabled,
+  or a Docker container runner with snapd configured.
+fix_code:
+  - language: yaml
+    label: "Install kubectl via apt instead of snap"
+    code: |
+      steps:
+        - name: Install kubectl
+          run: |
+            curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key \
+              | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
+            echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' \
+              | sudo tee /etc/apt/sources.list.d/kubernetes.list
+            sudo apt-get update
+            sudo apt-get install -y kubectl
+  - language: yaml
+    label: "Use dedicated setup actions instead of snap"
+    code: |
+      steps:
+        # Instead of: snap install kubectl --classic
+        - uses: azure/setup-kubectl@v4
+          with:
+            version: 'v1.30.0'
+
+        # Instead of: snap install helm --classic
+        - uses: azure/setup-helm@v4
+          with:
+            version: '3.14.0'
+
+        # Instead of: snap install aws-cli --classic
+        - name: Install AWS CLI v2
+          run: |
+            curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+            unzip awscliv2.zip
+            sudo ./aws/install
+prevention:
+  - "Audit your workflow for any `snap install` commands — GitHub-hosted runners cannot run snap packages"
+  - "Check if the tool has an official GitHub Action (setup-kubectl, setup-helm, etc.) before writing a manual install step"
+  - "For tools not on apt, prefer GitHub Releases binary downloads with `curl` and `chmod +x` over snap"
+  - "Self-hosted runners with a full Ubuntu desktop/server installation do support snap if needed"
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#software-installed-on-github-hosted-runners"
+    label: "GitHub Docs: Software installed on GitHub-hosted runners"
+  - url: "https://github.com/actions/runner-images/issues/1769"
+    label: "runner-images#1769: snap is not supported"

package/errors/runner-environment/ubuntu-systemctl-systemd-not-running.yml

@@ -0,0 +1,95 @@
+id: runner-environment-153
+title: "ubuntu runner systemctl fails — systemd not running as PID 1"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - systemd
+  - systemctl
+  - services
+  - daemon
+patterns:
+  - regex: 'System has not been booted with systemd as init system \(PID 1\)\. Can''t operate\.'
+    flags: i
+  - regex: 'Failed to connect to bus: No such file or directory'
+    flags: i
+  - regex: 'systemctl: command not found'
+    flags: i
+error_messages:
+  - "System has not been booted with systemd as init system (PID 1). Can't operate."
+  - "Failed to connect to bus: No such file or directory"
+  - "Failed to start postgresql.service: Unit not found."
+  - "System has not been booted with systemd"
+root_cause: |
+  GitHub-hosted Ubuntu runners do not run systemd as the init system (PID 1). The runner
+  process starts directly inside a container-like environment where systemd is never initialized.
+  Any workflow step that calls `sudo systemctl start <service>`, `systemctl enable <service>`,
+  or `systemctl status <service>` will immediately fail because the D-Bus socket and systemd
+  unit system are not present.
+
+  This is a fundamental architectural constraint of GitHub-hosted runners — they are ephemeral
+  VMs (not containers) but systemd is disabled to reduce boot time and resource overhead. The
+  pattern is extremely common when devs copy-paste service startup commands from their local
+  Linux environment or documentation into GitHub Actions run: steps.
+
+  Common affected services: PostgreSQL, MySQL, Redis, MongoDB, Nginx, Apache, RabbitMQ.
+fix: |
+  Replace `systemctl` calls with one of these approaches:
+
+  1. **Use GitHub Actions `services:` containers** — the recommended approach for databases and
+     message queues. GitHub spins up Docker containers alongside your job.
+
+  2. **Use direct daemon start commands** — start the service binary directly:
+     - PostgreSQL: `sudo -u postgres pg_ctl -D /etc/postgresql/*/main start`
+     - MySQL: `sudo mysqld_safe &`
+     - Redis: `redis-server --daemonize yes`
+
+  3. **Use `service` SysV command** — on Ubuntu runners, SysV init `service` works even without
+     systemd: `sudo service postgresql start`
+
+fix_code:
+  - language: yaml
+    label: "Use services: containers block (recommended for databases)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_PASSWORD: postgres
+              ports:
+                - 5432:5432
+              options: >-
+                --health-cmd pg_isready
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: npm test
+              env:
+                DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test
+  - language: yaml
+    label: "Use SysV 'service' command as systemctl fallback"
+    code: |
+      steps:
+        - name: Start PostgreSQL
+          run: |
+            sudo service postgresql start
+            sudo service postgresql status
+        - name: Create test database
+          run: |
+            sudo -u postgres psql -c "CREATE DATABASE testdb;"
+prevention:
+  - "Use the `services:` block in your workflow for databases and message queues — it's the GitHub Actions-native solution"
+  - "Replace `systemctl start X` with `sudo service X start` for SysV-compatible services"
+  - "For custom daemons, start them in the background with `&` and poll for readiness"
+  - "Never copy-paste `systemctl` commands from local Linux setup scripts into GitHub Actions without adaptation"
+docs:
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers"
+    label: "GitHub Docs: About service containers"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/creating-postgresql-service-containers"
+    label: "GitHub Docs: Creating PostgreSQL service containers"

package/errors/silent-failures/silent-failures-080.yml

@@ -0,0 +1,97 @@
+id: silent-failures-080
+title: "github.event.commits always empty array on pull_request events"
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull-request
+  - commits
+  - event-payload
+  - skip-ci
+  - multi-trigger
+patterns:
+  - regex: 'github\.event\.commits\[0\]'
+    flags: i
+  - regex: 'Cannot read propert\w+ of undefined.*message'
+    flags: i
+error_messages:
+  - "Error: Cannot read properties of undefined (reading 'message')"
+  - "github.event.commits[0] evaluates to null on pull_request events"
+  - "contains(github.event.commits[0].message, '[skip ci]') always false on PRs"
+root_cause: |
+  The `github.event.commits` array is only populated in `push` event payloads.
+  On `pull_request` events, `github.event.commits` is always an empty array `[]`.
+  Accessing `github.event.commits[0]` returns `null`, and
+  `github.event.commits[0].message` returns an empty string without throwing an
+  expression error.
+
+  This is the most common footgun when implementing "[skip ci]" commit message
+  detection: the condition works correctly for `push` events but silently never
+  triggers (never skips) on `pull_request` events. The workflow runs for every PR
+  push regardless of the commit message.
+
+  The issue affects any multi-trigger workflow with both `push:` and `pull_request:`
+  that reads commit data from the event payload.
+fix: |
+  Guard `github.event.commits` access by event type, or use PR-specific context:
+  1. Use `if: github.event_name == 'push'` before accessing commits.
+  2. For PR events, check `github.event.pull_request.title` or `github.event.pull_request.body`
+     for skip conditions.
+  3. Use the `actions/github-script` action to query commits via the REST API on PR events.
+  4. Consider separate workflows for push and pull_request to avoid cross-event payload confusion.
+fix_code:
+  - language: yaml
+    label: "Wrong: commit message check silently fails on pull_request events"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # github.event.commits[0].message is null on pull_request — condition always false
+          if: "!contains(github.event.commits[0].message, '[skip ci]')"
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Fix: guard by event type and use PR-appropriate skip signal"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Check skip condition
+              id: skip
+              run: |
+                SKIP=false
+                if [[ "${{ github.event_name }}" == "push" ]]; then
+                  # Commits array is available on push events
+                  if echo "${{ github.event.commits[0].message }}" | grep -q '\[skip ci\]'; then
+                    SKIP=true
+                  fi
+                elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
+                  # Check PR title or body for skip signal on PR events
+                  if echo "${{ github.event.pull_request.title }}" | grep -q '\[skip ci\]'; then
+                    SKIP=true
+                  fi
+                fi
+                echo "skip=$SKIP" >> "$GITHUB_OUTPUT"
+
+            - name: Run tests
+              if: steps.skip.outputs.skip != 'true'
+              run: npm test
+prevention:
+  - "Never access github.event.commits on workflows with pull_request triggers — it will always be empty."
+  - "Use separate workflows for push and pull_request if commit-message-based conditionals are required."
+  - "For PR skip conditions, use the PR title or body rather than commit messages."
+  - "Check which fields are populated for each event type in the GitHub webhook event payload documentation."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "Push webhook event payload (commits array)"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request"
+    label: "Pull request webhook event payload"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "Using conditions to control job execution"

package/errors/silent-failures/silent-failures-081.yml

@@ -0,0 +1,86 @@
+id: silent-failures-081
+title: '`needs.<job_id>.conclusion` does not exist — correct property is `result`; evaluates to empty string silently'
+category: silent-failures
+severity: silent-failure
+tags:
+  - needs-context
+  - job-result
+  - downstream-jobs
+  - if-condition
+  - empty-string
+  - notification-job
+patterns:
+  - regex: 'needs\.\w+\.conclusion'
+    flags: 'i'
+error_messages:
+  - "needs.<job_id>.conclusion evaluates to empty string — condition using .conclusion never fires"
+root_cause: |
+  The `needs` context exposes `.result` for each upstream job — NOT `.conclusion`.
+  Valid values for `needs.<job_id>.result` are: `success`, `failure`, `cancelled`,
+  and `skipped`.
+
+  The property `.conclusion` does not exist on the needs context object. Accessing
+  `needs.<job_id>.conclusion` silently evaluates to an empty string `""` with no
+  warning, error, or annotation in the workflow logs. The downstream job runs but the
+  `if:` condition never matches because `"" == 'failure'` is always false.
+
+  This confusion arises because the `steps` context exposes BOTH `.conclusion` and
+  `.outcome` for step results, leading developers to assume the needs context follows
+  the same property naming. The mismatch causes notification jobs, cleanup steps, and
+  failure-handler jobs to silently skip execution with no observable error.
+fix: |
+  Replace `.conclusion` with `.result` in all `needs` context expressions.
+
+    WRONG: if: needs.build.conclusion == 'failure'   # always empty string, never matches
+    RIGHT: if: needs.build.result == 'failure'        # correct
+
+  For aggregate checks, prefer the built-in status functions over manual needs.result
+  comparisons — `failure()`, `success()`, `cancelled()`, `always()` — which evaluate
+  the combined result of all upstream jobs automatically.
+fix_code:
+  - language: yaml
+    label: 'Correct: use needs.<job>.result not needs.<job>.conclusion'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+        notify-on-failure:
+          needs: [build]
+          # Use built-in failure() or explicit needs.<job>.result
+          if: failure()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send failure notification
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # .result values: success | failure | cancelled | skipped
+  - language: yaml
+    label: 'Multi-job downstream check using needs.result'
+    code: |
+      jobs:
+        deploy:
+          needs: [lint, test, build]
+          # Explicit per-job result check — use .result not .conclusion
+          if: >-
+            needs.lint.result == 'success' &&
+            needs.test.result == 'success' &&
+            needs.build.result == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "All upstream jobs succeeded"
+prevention:
+  - 'The needs context exposes `.result` only — `.conclusion` does not exist. Use `needs.<job>.result` for all downstream conditional checks.'
+  - 'Prefer the status check functions `failure()`, `success()`, `cancelled()`, `always()` in downstream job `if:` conditions — they aggregate all upstream job results automatically.'
+  - 'Add actionlint to CI — it reports references to undefined context properties including `needs.<job>.conclusion`, catching this mistake at review time.'
+  - 'When a notification or cleanup job silently skips, verify the `if:` condition uses `.result` and check the actual result value in the Actions run summary.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#needs-context'
+    label: 'GitHub Actions: needs context — result property'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'Using conditions to control job execution'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions'
+    label: 'Status check functions: failure(), success(), cancelled(), always()'

package/errors/triggers/triggers-059.yml

@@ -0,0 +1,106 @@
+id: triggers-059
+title: "workflow_call required: true inputs silently receive empty string when omitted by caller"
+category: triggers
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - inputs
+  - required
+  - validation
+patterns:
+  - regex: 'required.*input.*not provided'
+    flags: i
+  - regex: 'Input .+ is required but was not provided'
+    flags: i
+error_messages:
+  - "Input 'environment' is required but was not provided"
+  - "required: true input silently receives empty string when omitted from caller with:"
+root_cause: |
+  When a reusable workflow declares `on.workflow_call.inputs` with `required: true`,
+  GitHub does NOT enforce this requirement at call time via the REST API or from other
+  calling workflows. The `required: true` flag is informational documentation only —
+  it is not validated before the workflow runs.
+
+  When a calling workflow omits a required input from its `with:` block, the reusable
+  workflow receives an empty string `""` for the missing input with no error or warning.
+  The workflow starts and runs to whatever conclusion the empty input causes.
+
+  This leads to silent failures such as deploying to an undefined environment, running
+  against an empty target URL, or passing `""` to shell commands that produce incorrect
+  results. The bug is especially hard to find because the calling workflow shows a green
+  "success" until the silent empty input causes a downstream failure.
+fix: |
+  Explicitly validate all required inputs at the start of the reusable workflow:
+  1. Add an input-validation step as the FIRST step of the FIRST job that checks each
+     required input for emptiness and fails with a descriptive error.
+  2. Use `default:` values in `on.workflow_call.inputs` to handle omitted inputs
+     gracefully with a fallback rather than silently using empty string.
+  3. In calling workflows, always pass all inputs explicitly with `with:` — never
+     rely on `required: true` to catch missing inputs.
+fix_code:
+  - language: yaml
+    label: "Reusable workflow: validate required inputs at startup"
+    code: |
+      # .github/workflows/deploy.yml (reusable workflow)
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              required: true   # documentation only — NOT enforced by GitHub
+              type: string
+            target-url:
+              required: true
+              type: string
+
+      jobs:
+        validate-inputs:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate required inputs
+              run: |
+                ERRORS=()
+                if [[ -z "${{ inputs.environment }}" ]]; then
+                  ERRORS+=("Required input 'environment' was not provided")
+                fi
+                if [[ -z "${{ inputs.target-url }}" ]]; then
+                  ERRORS+=("Required input 'target-url' was not provided")
+                fi
+                if [[ ${#ERRORS[@]} -gt 0 ]]; then
+                  for ERR in "${ERRORS[@]}"; do
+                    echo "::error::$ERR"
+                  done
+                  exit 1
+                fi
+
+        deploy:
+          needs: validate-inputs
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ inputs.environment }}"
+  - language: yaml
+    label: "Fix: use default: values to avoid silent empty string behavior"
+    code: |
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              required: false
+              default: 'staging'   # explicit default instead of relying on required: true
+              type: string
+      
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ inputs.environment }}"  # always 'staging' if omitted
+prevention:
+  - "Treat required: true on workflow_call inputs as documentation only — always validate inside the reusable workflow."
+  - "Add a dedicated input-validation job as the first job in every reusable workflow with required inputs."
+  - "Prefer default: values over required: true when a sensible fallback exists."
+  - "In calling workflows, always explicitly pass all inputs in the with: block."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs"
+    label: "on.workflow_call.inputs syntax reference"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-called-workflow"
+    label: "Using inputs in a called workflow"

package/errors/yaml-syntax/yaml-syntax-054.yml

@@ -0,0 +1,94 @@
+id: yaml-syntax-054
+title: "env context silently empty in reusable workflow with: inputs"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - env-context
+  - with-inputs
+  - workflow-call
+  - context-availability
+patterns:
+  - regex: '"env" context is not available in this context'
+    flags: i
+  - regex: 'env context.*not available.*reusable'
+    flags: i
+error_messages:
+  - '"env" context is not available in this context'
+  - "Input evaluates to empty string when env context used in reusable workflow with:"
+root_cause: |
+  The `env` context is NOT available inside `jobs.<job_id>.with:` blocks used to
+  call reusable workflows. Unlike `jobs.<job_id>.steps.with:` (regular action steps,
+  which support `env` context), reusable workflow `with:` inputs are evaluated before
+  job-level environment variables are injected.
+
+  Using `${{ env.MY_VAR }}` in a reusable workflow `with:` block silently evaluates
+  to an empty string. No error is thrown and the reusable workflow receives `""` for
+  that input. The actionlint static linter reports:
+  `"env" context is not available in this context`.
+
+  This is explicitly documented in GitHub's context availability table — `env` is
+  available in `jobs.<job_id>.steps.with` but NOT in `jobs.<job_id>.with`.
+fix: |
+  Replace `env` context references in reusable workflow `with:` blocks with one of:
+  1. `vars` context — for repository or organization-level configuration variables
+     (Settings → Variables). Available in reusable workflow `with:`.
+  2. Inline literal values directly in `with:`.
+  3. Workflow-level `inputs:` context if the calling workflow is itself a reusable
+     workflow (chain input passing).
+  4. A prior job that captures the value and passes it via `needs.<job>.outputs`.
+fix_code:
+  - language: yaml
+    label: "Wrong: env context in reusable workflow with: (silently evaluates to empty string)"
+    code: |
+      env:
+        BASE_URL: 'https://api.example.com'
+        DEPLOY_ENV: 'production'
+
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api-url: ${{ env.BASE_URL }}    # silently empty — env unavailable in reusable with:
+            environment: ${{ env.DEPLOY_ENV }}  # also silently empty
+  - language: yaml
+    label: "Fix: use vars context or inline value"
+    code: |
+      # Set BASE_URL as a repository variable in Settings → Secrets and variables → Variables
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api-url: ${{ vars.BASE_URL }}       # vars IS available in reusable with:
+            environment: 'production'            # inline literal also works
+  - language: yaml
+    label: "Fix: pass via prior job output if value is dynamic"
+    code: |
+      jobs:
+        resolve-config:
+          runs-on: ubuntu-latest
+          outputs:
+            api-url: ${{ steps.config.outputs.url }}
+          steps:
+            - id: config
+              run: echo "url=$BASE_URL" >> "$GITHUB_OUTPUT"
+              env:
+                BASE_URL: ${{ env.BASE_URL }}  # env IS available in step env:
+
+        call-deploy:
+          needs: resolve-config
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api-url: ${{ needs.resolve-config.outputs.api-url }}  # needs context available
+prevention:
+  - "Consult the GitHub Actions context availability table before using contexts in reusable workflow with: blocks."
+  - "Prefer vars context (repository/org variables) over env for values shared across workflows."
+  - "Run actionlint in CI — it detects unavailable context usage and catches this before runtime."
+  - "If a reusable workflow input is silently empty, check context availability as the first debugging step."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Actions context availability table"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-called-workflow"
+    label: "Passing inputs and secrets to a called workflow"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint — static checker for GitHub Actions"

package/errors/yaml-syntax/yaml-syntax-055.yml

@@ -0,0 +1,88 @@
+id: yaml-syntax-055
+title: '`on.workflow_call.outputs.value` references `steps.<id>.outputs` — steps context unavailable at workflow scope; must use `jobs.<job_id>.outputs`'
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflow
+  - workflow_call
+  - outputs
+  - steps-context
+  - jobs-context
+  - empty-string
+  - scope
+patterns:
+  - regex: 'steps\.\w+\.outputs\.\w+'
+    flags: 'i'
+error_messages:
+  - "Reusable workflow output is empty — steps context not accessible in on.workflow_call.outputs.value"
+  - "on.workflow_call.outputs value references steps context which is not available at workflow scope"
+root_cause: |
+  In a reusable workflow, `on.workflow_call.outputs[*].value:` expressions are
+  evaluated at the WORKFLOW level, not within a job. The `steps` context is scoped to
+  a specific job and is only accessible inside that job's step expressions — it is
+  not visible at the top-level workflow scope where `on.workflow_call.outputs` lives.
+
+  Using `${{ steps.upload.outputs.artifact-id }}` in the `value:` field silently
+  evaluates to an empty string. No error, warning, or annotation is raised; the
+  caller simply receives an empty output value.
+
+  The correct pattern requires two explicit hops:
+  1. Capture the step output at the JOB level using the job's `outputs:` block.
+  2. Reference the JOB output at the WORKFLOW level using `${{ jobs.<job_id>.outputs.<key> }}`.
+
+  Note: this is distinct from yaml-syntax-032 (jobs.<id>.result empty in workflow_call
+  outputs) which covers the result property specifically, not step output propagation.
+fix: |
+  Bridge step outputs up through the job's `outputs:` block first, then reference the
+  job output in `on.workflow_call.outputs.value`.
+
+  Pattern:
+    step writes to GITHUB_OUTPUT (or action output)
+      → job outputs: exposes it as jobs.<job_id>.outputs.<key>
+        → on.workflow_call.outputs.value references jobs.<job_id>.outputs.<key>
+fix_code:
+  - language: yaml
+    label: 'Correct two-hop output propagation for reusable workflows'
+    code: |
+      on:
+        workflow_call:
+          outputs:
+            artifact-id:
+              description: 'ID of the uploaded build artifact'
+              # CORRECT: reference job-level output
+              value: ${{ jobs.build.outputs.artifact-id }}
+              # WRONG (silent empty string):
+              # value: ${{ steps.upload.outputs.artifact-id }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            # Hop 1: expose step output at job level
+            artifact-id: ${{ steps.upload.outputs.artifact-id }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: npm ci && npm run build
+
+            - name: Upload artifact
+              id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+            # Hop 2: job outputs block above captures steps.upload.outputs.artifact-id
+            # Hop 3: on.workflow_call.outputs.value references jobs.build.outputs.artifact-id
+prevention:
+  - 'The `steps` context is job-scoped. Always bridge step outputs through the job `outputs:` block before referencing them at workflow level in `on.workflow_call.outputs.value:`.'
+  - 'Use actionlint to statically analyze reusable workflow output expressions — it reports invalid context usage at workflow scope.'
+  - 'When a reusable workflow output is unexpectedly empty in the caller, check whether the `value:` expression uses `steps.` (wrong scope) vs `jobs.` (correct scope).'
+  - 'Each output needs both a job-level `outputs:` mapping AND a workflow-level `on.workflow_call.outputs[*].value:` reference — missing either hop silently returns empty string.'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow'
+    label: 'Reusable workflows: using outputs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'Passing information between jobs (job outputs)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context'
+    label: 'Steps context — job-scoped, not available at workflow level'

package/package.json

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