@htekdev/actions-debugger 1.0.87 → 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-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-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/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.87",
+  "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",