@htekdev/actions-debugger 1.0.87 → 1.0.89

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/silent-failures/silent-failures-082.yml

@@ -0,0 +1,93 @@
+id: silent-failures-082
+title: "pull_request_target checkout defaults to base branch, not PR head"
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull_request_target
+  - checkout
+  - security
+  - fork
+  - base-branch
+patterns:
+  - regex: 'on:\s*\n\s+pull_request_target'
+    flags: 'im'
+  - regex: 'pull_request_target'
+    flags: 'i'
+error_messages:
+  - "Workflow runs on base branch code instead of PR contributor changes"
+  - "Tests pass on base but fail on PR code with no visible error in logs"
+root_cause: |
+  When a workflow is triggered by `pull_request_target`, GitHub Actions runs the workflow
+  from the TARGET repository's base branch — not the contributor's PR head. This is
+  intentional: `pull_request_target` provides write-level token access (for labeling,
+  commenting, posting status checks), so GitHub protects secrets by refusing to run
+  untrusted fork code with elevated permissions.
+
+  As a result, `actions/checkout` checks out `github.sha`, which resolves to the merge
+  base commit on the target branch. Any tests, linting, or code analysis in this
+  workflow validate the base branch, not the contributor's changes. The workflow
+  succeeds silently while testing the wrong code.
+fix: |
+  Option 1 (recommended — safe): Use `pull_request` (not `pull_request_target`) for
+  running PR code. `pull_request` triggers run with read-only tokens and check out the
+  PR head by default. Use `pull_request_target` only for privileged actions like posting
+  comments or labels.
+
+  Option 2 (explicit checkout — use with caution): Explicitly check out the PR head
+  using `github.event.pull_request.head.sha`. Only do this if you fully trust all
+  contributors and understand that fork code will execute with the repository write token.
+fix_code:
+  - language: yaml
+    label: "Recommended: use pull_request for code execution, pull_request_target for privileged writes"
+    code: |
+      # Workflow 1: run tests on PR code (read-only, safe for forks)
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              # Checks out PR head automatically — no ref: override needed
+            - run: npm test
+
+      ---
+      # Workflow 2: post labels (write access via pull_request_target)
+      on:
+        pull_request_target:
+          types: [opened]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            - uses: actions/labeler@v5
+              # Never runs contributor code here — only labels the PR
+  - language: yaml
+    label: "If you must run PR code under pull_request_target (risky)"
+    code: |
+      on:
+        pull_request_target:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+                # WARNING: executes untrusted fork code with write-level token
+prevention:
+  - "Use pull_request (not pull_request_target) for workflows that run code — pull_request tokens are read-only and checkout the PR head correctly by default"
+  - "Reserve pull_request_target for privileged write-only actions: posting comments, applying labels, updating statuses — never checkout and execute untrusted PR code in these workflows"
+  - "If CI consistently passes but reviewers find bugs tests should catch, verify which commit your checkout step is using by printing github.sha vs github.event.pull_request.head.sha"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "pull_request_target event — security considerations"
+  - url: "https://securitylab.github.com/research/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab: Preventing pwn requests (pull_request_target risks)"

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

@@ -0,0 +1,64 @@
+id: silent-failures-083
+title: "matrix strategy fail-fast true by default silently cancels all remaining jobs on first failure"
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - fail-fast
+  - cancellation
+  - strategy
+  - parallel-jobs
+patterns:
+  - regex: 'strategy:\s*\n\s+matrix:'
+    flags: 'im'
+  - regex: 'Some jobs were not executed because a previous required job failed'
+    flags: 'i'
+error_messages:
+  - "Some jobs were not executed because a previous required job failed"
+  - "Skipping this step because a previous step failed or the workflow was cancelled"
+  - "This job was cancelled because another job in the workflow failed"
+root_cause: |
+  GitHub Actions matrix strategy has `fail-fast: true` as the default. When any single
+  matrix job fails, GitHub immediately cancels all remaining in-progress and queued
+  matrix jobs from the same workflow run.
+
+  This means:
+  - You only see the failure from the first (or earliest) failing matrix combination
+  - All other combinations — whether they would pass or fail — are cancelled immediately
+  - The workflow summary shows cancelled jobs with no diagnostic information
+  - Developers may spend time fixing the first failure only to discover a second unrelated
+    failure in a different matrix combination afterward
+
+  Many developers set up matrix builds specifically to validate across multiple
+  OS/language version combinations and expect every combination to run to completion.
+fix: |
+  Explicitly set `fail-fast: false` in your matrix strategy to allow all matrix jobs to
+  run to completion regardless of individual failures. This provides a complete picture
+  of which matrix combinations are broken.
+fix_code:
+  - language: yaml
+    label: "Set fail-fast: false to run all matrix combinations to completion"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false    # default is true — set false for full matrix visibility
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: [18, 20, 22]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+            - run: npm test
+prevention:
+  - "Always explicitly set fail-fast: false when you want all matrix combinations to run — for example when building cross-platform or cross-version compatibility matrices"
+  - "The default fail-fast: true is intentional for workflows where you only care about any single failure (saves CI minutes), but must be changed when you need full failure visibility"
+  - "If matrix jobs are silently cancelled and show no error output, check whether fail-fast: true (or its absence — the default) is the cause"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast"
+    label: "jobs.<job_id>.strategy.fail-fast documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix"
+    label: "Matrix strategy documentation"

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

@@ -0,0 +1,96 @@
+id: silent-failures-084
+title: "github.sha on pull_request event is the ephemeral merge commit SHA, not the PR head commit"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-sha
+  - pull_request
+  - merge-commit
+  - docker
+  - tagging
+  - status-checks
+patterns:
+  - regex: '\$\{\{\s*github\.sha\s*\}\}'
+    flags: 'i'
+  - regex: 'github\.sha'
+    flags: 'i'
+error_messages:
+  - "Docker image tagged with SHA not found in git history"
+  - "Deployment status does not appear on the PR commit"
+  - "Commit status check not visible on pull request"
+root_cause: |
+  On `pull_request` events, `github.sha` is NOT the PR branch's head commit SHA. It is
+  the SHA of a temporary merge commit that GitHub creates automatically to simulate
+  "what would happen if this PR were merged right now." This ephemeral merge commit:
+
+  - Does NOT appear in the repository's git history
+  - Changes every time the base branch advances, even with no new PR commits
+  - Is not accessible via normal git operations outside the workflow run
+
+  Consequences developers hit in the wild:
+  - Docker images tagged with `github.sha` have tags that don't correspond to any real
+    commit, making rollbacks and tracing impossible
+  - Commit status checks or deployment markers posted to `github.sha` don't appear on
+    any commit in the PR and are effectively invisible to reviewers
+  - Scripts that fetch the commit from the API using github.sha return 404
+
+  The actual PR head commit SHA is available via `github.event.pull_request.head.sha`.
+fix: |
+  Use `github.event.pull_request.head.sha` to get the actual PR head commit on
+  pull_request events. For workflows triggered by both push and pull_request, use a
+  conditional to select the correct SHA per event type.
+fix_code:
+  - language: yaml
+    label: "Get the correct SHA for both push and pull_request events"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Resolve commit SHA
+              id: sha
+              run: |
+                if [ "${{ github.event_name }}" = "pull_request" ]; then
+                  echo "value=${{ github.event.pull_request.head.sha }}" >> $GITHUB_OUTPUT
+                else
+                  echo "value=${{ github.sha }}" >> $GITHUB_OUTPUT
+                fi
+
+            - name: Tag Docker image with correct SHA
+              run: |
+                docker build -t myapp:${{ steps.sha.outputs.value }} .
+                docker push myapp:${{ steps.sha.outputs.value }}
+  - language: yaml
+    label: "Post commit status to the correct PR head SHA"
+    code: |
+      on:
+        pull_request:
+
+      jobs:
+        status:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Post status to actual PR commit
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  // Use PR head SHA, not github.sha (merge commit)
+                  await github.rest.repos.createCommitStatus({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    sha: context.payload.pull_request.head.sha,
+                    state: 'success',
+                    description: 'Build passed',
+                    context: 'ci/build'
+                  });
+prevention:
+  - "Never tag Docker images or create commit statuses using github.sha on pull_request events — use github.event.pull_request.head.sha for the real PR head"
+  - "If deployment statuses or commit checks are missing from PR commits, verify you are not posting them to github.sha (the merge commit)"
+  - "The merge commit SHA changes every time the base branch gets new commits, even without new PR activity — this makes github.sha unstable for artifact tagging on PRs"
+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 — note on github.sha merge commit"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub context — sha property"

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/errors/yaml-syntax/yaml-syntax-056.yml

@@ -0,0 +1,87 @@
+id: yaml-syntax-056
+title: "env context unavailable inside with: inputs of uses: steps"
+category: yaml-syntax
+severity: error
+tags:
+  - env-context
+  - with-inputs
+  - uses
+  - expression-context
+  - action-inputs
+patterns:
+  - regex: "Unrecognized named-value: 'env'"
+    flags: 'i'
+  - regex: 'Invalid workflow file.*Unrecognized named-value'
+    flags: 'i'
+error_messages:
+  - "Unrecognized named-value: 'env'. Located at position 1 within expression: env.MY_VAR"
+  - "Invalid workflow file: .github/workflows/ci.yml (Line 14, Col 15): Unrecognized named-value: 'env'"
+  - "The workflow is not valid. .github/workflows/build.yml: Unrecognized named-value: 'env'"
+root_cause: |
+  The `env` context is NOT available inside the `with:` input block of a `uses:` step.
+  GitHub Actions evaluates `uses:` step inputs using a restricted set of contexts, and
+  `env` is explicitly excluded because env var values may depend on previous step
+  outputs (which are also unavailable at `with:` evaluation time).
+
+  Contexts available in `with:` inputs: `github`, `needs`, `strategy`, `matrix`,
+  `secrets`, `inputs`, `vars`, and `steps` (but only from previously completed steps).
+  The `env` context, `runner` context, and job-level env vars are all unavailable.
+
+  This catches developers who define env vars at the workflow or job level and then try
+  to pass them as action inputs, which fails with "Unrecognized named-value: 'env'".
+fix: |
+  Three options:
+  1. Reference the value directly (hardcoded or via a different supported context)
+  2. Use `vars` context (repository/org variables) — available in `with:` blocks
+  3. Capture the env value in a prior step's GITHUB_OUTPUT and reference it via
+     `steps.<id>.outputs.<name>` in the subsequent `uses:` step
+fix_code:
+  - language: yaml
+    label: "Wrong: env context in with: inputs (causes parse error)"
+    code: |
+      env:
+        API_URL: https://api.example.com
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: my-org/deploy-action@v1
+              with:
+                url: ${{ env.API_URL }}   # ERROR: Unrecognized named-value: 'env'
+  - language: yaml
+    label: "Fix option A: use vars context (repository variable)"
+    code: |
+      # Set API_URL as a repository variable in Settings > Secrets and variables > Variables
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: my-org/deploy-action@v1
+              with:
+                url: ${{ vars.API_URL }}   # vars context IS available in with:
+  - language: yaml
+    label: "Fix option B: capture in prior step output, reference via steps context"
+    code: |
+      env:
+        API_URL: https://api.example.com
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - id: config
+              run: echo "api_url=$API_URL" >> $GITHUB_OUTPUT
+
+            - uses: my-org/deploy-action@v1
+              with:
+                url: ${{ steps.config.outputs.api_url }}   # steps context IS available
+prevention:
+  - "In with: inputs, only use: github, needs, strategy, matrix, secrets, inputs, vars, and steps (from prior completed steps) — never env or runner"
+  - "For static configuration values, prefer repository variables (vars context) over env — vars are available everywhere env is not"
+  - "If you need a dynamically computed value (from a script or env var) in a with: block, capture it to GITHUB_OUTPUT in a prior step and reference via steps.<id>.outputs"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "Context availability table — which contexts are valid per syntax location"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith"
+    label: "jobs.<job_id>.steps[*].with syntax documentation"

package/package.json

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