@htekdev/actions-debugger 1.0.7 → 1.0.9

package/errors/caching-artifacts/upload-artifact-v4-same-name-409-conflict.yml

@@ -0,0 +1,145 @@
+id: caching-artifacts-012
+title: "upload-artifact v4 Rejects Duplicate Artifact Names from Multiple Jobs (409 Conflict)"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - artifact-v4
+  - matrix
+  - parallel-jobs
+  - 409
+  - immutability
+patterns:
+  - regex: "Failed to CreateArtifact.*409.*Conflict.*artifact.*already exists"
+    flags: "i"
+  - regex: "artifact.*already exists.*workflow run|duplicate.*artifact.*name"
+    flags: "i"
+  - regex: "Received non-retryable error.*409.*Conflict"
+    flags: "i"
+error_messages:
+  - "Failed to CreateArtifact: Received non-retryable error: Failed request: (409) Conflict: an artifact with this name already exists on the workflow run"
+  - "Error: ENOENT: no such file or directory — artifact upload failed with conflict"
+  - "Upload failed: 409 Conflict — Artifact 'build-output' already exists"
+root_cause: |
+  **actions/upload-artifact v4** (backed by the v2 `@actions/artifact` client) makes
+  artifacts **immutable and job-scoped by default**. Once an artifact name is uploaded
+  by any job in a workflow run, that name is locked — a second job attempting to upload
+  an artifact with the same name will receive a `409 Conflict` error from the Artifact
+  API and the upload fails.
+
+  This is a **breaking behavior change from v3**, which allowed multiple jobs to
+  append to the same artifact name. v4 deliberately prevents this to ensure artifact
+  content integrity and predictable downloads.
+
+  **Common scenarios that trigger this:**
+
+  1. **Matrix jobs** — all matrix jobs use the same artifact name (e.g., `build-output`)
+     and upload in parallel; only the first to complete succeeds.
+
+  2. **Retry logic** — a job is retried (manually or via `retry-on-failure`) and the
+     original run already uploaded the artifact under the same name.
+
+  3. **Split test/build jobs** — multiple parallel jobs each generate and upload an
+     artifact with a shared generic name (e.g., `test-results`).
+
+  4. **Copy-pasted workflows** — two separate jobs have identical `upload-artifact`
+     steps with the same name.
+
+  The artifact immutability change was introduced to enable the new artifact download
+  model where artifacts are uniquely addressable and not corrupted by multiple writers.
+fix: |
+  **Use unique artifact names per job.** The standard pattern is to embed job/matrix
+  context in the artifact name so each upload is distinct.
+
+  For matrix jobs, include the matrix value in the name. For parallel jobs, include
+  the job name. The v4 `download-artifact` action supports wildcard patterns, so all
+  job-scoped artifacts can be downloaded together in a merge step.
+fix_code:
+  - language: yaml
+    label: "Matrix jobs — include matrix value in artifact name"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            # ❌ Causes 409: all matrix jobs use same name
+            # - uses: actions/upload-artifact@v4
+            #   with:
+            #     name: build-output
+            #     path: dist/
+
+            # ✅ Unique name per matrix dimension
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output-${{ matrix.os }}
+                path: dist/
+
+        package:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            # ✅ Download all matrix artifacts with wildcard
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: build-output-*
+                merge-multiple: true
+                path: dist/
+  - language: yaml
+    label: "Parallel jobs — unique names with merge step"
+    code: |
+      jobs:
+        test-unit:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test -- --reporter=junit --output-file=test-results.xml
+            - uses: actions/upload-artifact@v4
+              with:
+                name: test-results-unit      # unique name
+                path: test-results.xml
+
+        test-integration:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run test:integration -- --output-file=test-results.xml
+            - uses: actions/upload-artifact@v4
+              with:
+                name: test-results-integration    # unique name
+                path: test-results.xml
+
+        report:
+          needs: [test-unit, test-integration]
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: test-results-*
+                merge-multiple: true
+                path: all-results/
+prevention:
+  - "Always include a unique identifier in artifact names when multiple jobs upload
+    artifacts — use `${{ matrix.* }}`, `${{ github.job }}`, or a descriptive suffix."
+  - "Treat artifact names like immutable keys: once uploaded in a run, they cannot be
+    overwritten; design names accordingly."
+  - "Use `download-artifact@v4` with `pattern:` and `merge-multiple: true` to collect
+    artifacts from multiple jobs into a single directory in a downstream job."
+  - "If your workflow retries jobs automatically, include the attempt number
+    (`${{ github.run_attempt }}`) in the artifact name to avoid conflicts on retry."
+docs:
+  - url: "https://github.com/actions/upload-artifact/issues/478"
+    label: "actions/upload-artifact#478 — 409 Conflict: artifact with this name already exists"
+  - url: "https://github.com/actions/upload-artifact/blob/main/RELEASES.md"
+    label: "upload-artifact v4 release notes — immutability change"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "GitHub Docs: Storing and sharing data from a workflow"
+  - url: "https://github.com/actions/download-artifact?tab=readme-ov-file#download-multiple-artifacts"
+    label: "download-artifact: Downloading multiple artifacts with patterns"

package/errors/concurrency-timing/concurrency-group-name-collision.yml

@@ -0,0 +1,165 @@
+id: concurrency-timing-009
+title: "Concurrency Group Name Collision Cancels Unrelated Workflows"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - concurrency-group
+  - cancel-in-progress
+  - workflow-cancellation
+  - naming
+  - cross-workflow
+patterns:
+  - regex: "concurrency.*group.*cancelled|run.*cancelled.*concurrency"
+    flags: "i"
+  - regex: "previous run.*same concurrency group.*cancelled"
+    flags: "i"
+  - regex: "workflow run.*cancelled.*due to.*concurrency"
+    flags: "i"
+error_messages:
+  - "This workflow run was cancelled because a more recent run with the same concurrency group is in progress."
+  - "Workflow cancelled: superseded by a newer run in the same concurrency group."
+  - "Run #XXXX was cancelled because run #YYYY (same concurrency group 'deploy') is queued."
+root_cause: |
+  GitHub Actions concurrency groups operate **across all workflows** that share the
+  same group name string in the same repository. If two different workflows (or two
+  jobs in different workflows) declare the same `concurrency.group` name, they compete
+  for the same queue — leading to unintended cancellations between completely unrelated
+  workflows.
+
+  **Example of the collision pattern:**
+  ```yaml
+  # workflow-a.yml — CI pipeline
+  concurrency:
+    group: deploy
+    cancel-in-progress: true
+
+  # workflow-b.yml — Release pipeline (independent)
+  concurrency:
+    group: deploy        # ← same name! collides with workflow-a
+    cancel-in-progress: true
+  ```
+
+  In this example, triggering `workflow-b` cancels any in-progress run of `workflow-a`
+  and vice versa, even though they are completely independent processes.
+
+  **Common sources of collisions:**
+  - Copy-pasting a workflow file and forgetting to rename the concurrency group
+  - Using generic names like `deploy`, `build`, `ci`, `test`
+  - Multiple reusable workflows called from different callers with the same
+    `concurrency.group` in the caller
+  - Organization-wide template workflows with hardcoded group names
+
+  **Why this is a silent failure:** The cancellation log message appears in the
+  cancelled workflow run, but developers may not notice or may attribute the cancellation
+  to an unrelated cause. The triggering workflow (the one that caused the cancellation)
+  shows no indication it cancelled another workflow.
+
+  **Note:** Starting May 2026, GitHub Actions added support for **larger concurrency
+  queues** (`queue: max` option), allowing more pending runs instead of cancelling them.
+  This reduces pain but does not eliminate collisions caused by shared group names.
+fix: |
+  Make concurrency group names unique and descriptive by including the workflow name,
+  branch/ref, and optionally the event type. Never use generic single-word names
+  like `deploy`, `ci`, or `build` as the sole concurrency group name.
+
+  A safe pattern is: `${{ github.workflow }}-${{ github.ref }}`
+  This scopes the group to the specific workflow and branch combination, preventing
+  cross-workflow and cross-branch collisions.
+fix_code:
+  - language: yaml
+    label: "Use workflow + ref in concurrency group name"
+    code: |
+      # ✅ Safe pattern: workflow name + branch prevents cross-workflow collisions
+      name: Deploy Production
+
+      on:
+        push:
+          branches: [main]
+
+      concurrency:
+        # Unique per workflow + branch combination
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: "Per-PR concurrency — cancel superseded PR runs only"
+    code: |
+      # ✅ Scope to PR number — only cancels stale runs of the same PR
+      name: CI
+
+      on:
+        pull_request:
+
+      concurrency:
+        group: ${{ github.workflow }}-pr-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Job-level concurrency — scope to specific job, not whole workflow"
+    code: |
+      name: CI + Deploy
+
+      on:
+        push:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # No concurrency on test job — let tests always run
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          # Concurrency only on deploy, scoped to this specific workflow + job
+          concurrency:
+            group: ${{ github.workflow }}-deploy-${{ github.ref }}
+            cancel-in-progress: false  # queue deploys, don't cancel them
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: "Larger queue option (May 2026+) — allow pending runs instead of cancelling"
+    code: |
+      # ✅ Use larger queues to queue runs instead of cancelling
+      # Requires GitHub Actions concurrency queue support (May 2026+)
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: false   # do not cancel; queue instead
+        # queue: max                 # allow maximum pending runs (if supported)
+prevention:
+  - "Always include `${{ github.workflow }}` in the concurrency group name to prevent
+    cross-workflow collisions — bare names like `deploy` or `build` are collision-prone."
+  - "Include the ref (`${{ github.ref }}`) in group names so parallel PRs/branches
+    don't cancel each other's runs."
+  - "Audit all workflow files for concurrency group names when onboarding new workflows
+    into a repository — duplicates cause mysterious cancellations that are hard to trace."
+  - "Use job-level concurrency (not workflow-level) when only certain jobs (e.g., deploy)
+    need serialization — keep CI/test jobs unrestricted."
+  - "Document the concurrency group naming convention in your repository's CONTRIBUTING
+    or workflow guidelines so future contributors follow the same pattern."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs"
+    label: "GitHub Docs: Control the concurrency of workflows and jobs"
+  - url: "https://github.blog/changelog/2026-05-07-github-actions-concurrency-groups-now-allow-larger-queues"
+    label: "GitHub Changelog: Concurrency groups now allow larger queues (May 2026)"
+  - url: "https://oneuptime.com/blog/post/2026-01-25-github-actions-concurrency-control/view"
+    label: "GitHub Actions Concurrency Control — best practices blog post"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs#example-using-concurrency-to-cancel-any-in-progress-job-or-run"
+    label: "GitHub Docs: Concurrency examples — cancel in-progress"

package/errors/known-unsolved/upload-artifact-v4-ghes-not-supported.yml

@@ -0,0 +1,120 @@
+id: known-unsolved-010
+title: "upload-artifact v4 and download-artifact v4 Not Supported on GitHub Enterprise Server"
+category: known-unsolved
+severity: error
+tags:
+  - upload-artifact
+  - download-artifact
+  - artifact-v4
+  - ghes
+  - github-enterprise-server
+  - compatibility
+  - enterprise
+patterns:
+  - regex: "@actions/artifact v2\\.0\\.0.*not.*supported.*GHES|upload-artifact@v4.*not.*supported.*GHES"
+    flags: "i"
+  - regex: "download-artifact@v4.*not currently supported on GHES"
+    flags: "i"
+  - regex: "requires.*newer.*version.*GHES|GHES.*does not support.*artifact.*v[234]"
+    flags: "i"
+error_messages:
+  - "Error: @actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES"
+  - "Error: upload-artifact@v4 is not supported on your current GHES version. Use v3 instead."
+  - "Failed to create artifact: The artifact service is not available on this instance"
+root_cause: |
+  **actions/upload-artifact v4** and **actions/download-artifact v4** depend on a
+  new Artifact API (`@actions/artifact` v2+) that uses the Blob service and updated
+  artifact storage endpoints introduced in GitHub.com in late 2023. This API is
+  **not available on GitHub Enterprise Server (GHES)** instances running versions
+  prior to the minimum supported release for the new artifact service.
+
+  As of mid-2026, artifact v4 support on GHES has a version gate. GHES instances
+  that have not been upgraded to the minimum supported version will fail immediately
+  when any workflow step uses `upload-artifact@v4` or `download-artifact@v4`, with
+  a clear error message indicating the feature is unsupported.
+
+  **Key facts:**
+  - `upload-artifact@v3` and `download-artifact@v3` continue to work on all GHES versions
+  - There is no workaround that makes v4 work on unsupported GHES versions
+  - Self-hosted runners connected to GHES are subject to the same restriction as
+    GitHub-hosted runners on that instance
+  - The error is immediate (not a race condition or transient issue) — the artifact
+    service API rejects the request at connection time
+
+  **Impact:** Teams that copy workflows from GitHub.com repositories or follow
+  documentation written for GitHub.com find their enterprise CI broken after upgrading
+  actions to v4. The fix is to pin back to v3 on GHES or upgrade the GHES instance.
+fix: |
+  **Option 1 (recommended for most teams):** Pin `upload-artifact` and
+  `download-artifact` to `@v3` on your GHES-connected workflows until your GHES
+  instance is upgraded to a version that supports the new artifact service.
+
+  **Option 2:** Upgrade your GHES instance to the minimum version that supports
+  artifact v4. Consult the GHES release notes to find the minimum supported version.
+
+  **Option 3:** Use conditional version selection based on the `github.server_url`
+  context to use v4 on GitHub.com and v3 on GHES.
+fix_code:
+  - language: yaml
+    label: "Pin to v3 on GHES instances"
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            # ✅ Use v3 on GHES until your instance supports v4
+            - uses: actions/upload-artifact@v3
+              with:
+                name: build-output
+                path: dist/
+                retention-days: 7
+
+        deploy:
+          needs: build
+          runs-on: self-hosted
+          steps:
+            # ✅ Match the upload version for download
+            - uses: actions/download-artifact@v3
+              with:
+                name: build-output
+                path: dist/
+  - language: yaml
+    label: "Conditional version — v4 on GitHub.com, v3 on GHES"
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ github.server_url == 'https://github.com' && 'ubuntu-latest' || 'self-hosted' }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            # GitHub.com: use v4; GHES: use v3
+            - uses: ${{ github.server_url == 'https://github.com' && 'actions/upload-artifact@v4' || 'actions/upload-artifact@v3' }}
+              with:
+                name: build-output
+                path: dist/
+prevention:
+  - "Before upgrading to upload-artifact@v4 in a repository, verify whether the
+    repository is hosted on GitHub.com or a GHES instance."
+  - "For multi-environment repositories (same workflow runs on both GitHub.com and GHES),
+    use conditional `uses:` expressions or maintain separate workflow files per environment."
+  - "Monitor GHES release notes for artifact v4 support announcements before upgrading
+    enterprise workflows."
+  - "Pin action versions explicitly in GHES-hosted workflows — avoid floating `@latest`
+    tags that may resolve to v4 on GHES before the instance supports it."
+docs:
+  - url: "https://stackoverflow.com/questions/79267706/error-actions-artifact-v2-0-0-upload-artifactv4-and-download-artifactv4"
+    label: "Stack Overflow: upload-artifact@v4 and download-artifact@v4 not supported on GHES"
+  - url: "https://github.com/actions/upload-artifact/blob/main/RELEASES.md"
+    label: "upload-artifact v4 release notes — GHES compatibility notes"
+  - url: "https://docs.github.com/en/enterprise-server@latest/admin/release-notes"
+    label: "GitHub Enterprise Server release notes"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "GitHub Docs: Storing and sharing data from a workflow"

package/errors/runner-environment/docker-29-compose-v2-40-breaking.yml

@@ -0,0 +1,144 @@
+id: runner-environment-031
+title: "Docker 29.1 + Compose 2.40.3 Runner Update Breaks Compose Commands"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-compose
+  - docker-29
+  - compose-v2
+  - ubuntu
+  - windows
+  - runner-image-update
+patterns:
+  - regex: "docker compose.*unknown flag|unknown flag.*docker compose"
+    flags: "i"
+  - regex: "docker-compose.*command not found|docker-compose.*deprecated"
+    flags: "i"
+  - regex: "compose.*unknown command|error.*compose.*not a docker command"
+    flags: "i"
+  - regex: "docker compose.*plugin.*not found|failed to get plugins"
+    flags: "i"
+error_messages:
+  - "docker-compose: command not found"
+  - "unknown flag: --compatibility"
+  - "unknown shorthand flag: 'f' in -f"
+  - "Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.25"
+  - "'docker compose' requires at least 1 argument"
+root_cause: |
+  On **February 9, 2026**, GitHub pushed an update to Ubuntu and Windows runner images
+  that bumped Docker Server and Client from 28.x to **29.1.*** and Docker Compose from
+  2.x to **2.40.3** (announced in actions/runner-images#13474).
+
+  For Ubuntu 24.04, the update was **rolled back** on February 20, 2026 due to multiple
+  reported issues (#13682, #13691, #13684) and is being re-evaluated (tracked in
+  #14105). The Windows runner update proceeded.
+
+  **Breaking changes in Docker Compose 2.40.x and Docker 29.x:**
+
+  1. **`docker-compose` v1 binary removed** — Many older workflows use the hyphenated
+     `docker-compose` command (Compose v1). As of Docker Compose v2, only the plugin
+     form `docker compose` (no hyphen) is installed. Workflows with
+     `run: docker-compose up -d` fail with `command not found`.
+
+  2. **`--compatibility` flag removed** — The `docker compose --compatibility` flag
+     (for mapping v2 configs to v2-compatible behavior) was removed in 2.40.x.
+     Workflows that use `docker compose --compatibility up` fail.
+
+  3. **API version minimums** — Docker 29 raises the minimum supported Docker daemon
+     API version, breaking some older base images in service containers that use the
+     Docker socket with old clients.
+
+  4. **`COMPOSE_DOCKER_CLI_BUILD` env var deprecated** — Setting
+     `COMPOSE_DOCKER_CLI_BUILD=1` no longer has any effect; BuildKit is always used.
+
+  5. **Docker 29.5 `CLONE_NEWTIME` private time namespaces** — Docker 29.5 (released
+     May 2026) enables private time namespaces by default on kernels ≥ 5.6, which
+     breaks Docker-socket-passthrough patterns used in Cloud Native Buildpacks (CNB)
+     lifecycle builds. Buildpack builds via `pack build` or Spring Boot's built-in
+     Buildpacks fail silently or with lifecycle container errors.
+fix: |
+  **For `docker-compose` → `docker compose` migration:**
+  Replace all `docker-compose` (hyphenated) invocations with `docker compose` (space).
+  This is the most common fix.
+
+  **For `--compatibility` flag removal:**
+  Remove the `--compatibility` flag. Docker Compose v2 handles modern compose file
+  formats natively without this flag.
+
+  **For CNB/Buildpack Docker socket passthrough (Docker 29.5+):**
+  Mount the Docker socket without private time namespaces by using
+  `--security-opt=no-new-privileges:false` or by setting
+  `DOCKER_HOST` to use a sidecar daemon.
+
+  **For pinning Docker version on self-hosted runners:**
+  Pin to Docker 28.x until your Compose files and build pipelines are validated against
+  29.x.
+fix_code:
+  - language: yaml
+    label: "Replace docker-compose (v1) with docker compose (v2 plugin)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ Old (docker-compose v1 — removed)
+            # - run: docker-compose up -d
+            # - run: docker-compose --compatibility up -d
+
+            # ✅ New (docker compose v2 plugin)
+            - name: Start services
+              run: docker compose up -d
+
+            - name: Run tests
+              run: docker compose exec app npm test
+
+            - name: Tear down
+              run: docker compose down
+  - language: yaml
+    label: "Verify Docker and Compose versions in workflow"
+    code: |
+      jobs:
+        debug:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check Docker version
+              run: |
+                docker version
+                docker compose version
+                # If docker-compose (v1) is needed, install it explicitly:
+                # pip install docker-compose
+  - language: yaml
+    label: "Pin Docker version for self-hosted runners sensitive to 29.x changes"
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          steps:
+            - name: Pin Docker to 28.x (if 29.x breaks your workflow)
+              run: |
+                sudo apt-get remove -y docker-ce docker-ce-cli
+                sudo apt-get install -y docker-ce=5:28.0.4-1~ubuntu.24.04~noble \
+                  docker-ce-cli=5:28.0.4-1~ubuntu.24.04~noble
+prevention:
+  - "Migrate from `docker-compose` (v1) to `docker compose` (v2 plugin) immediately —
+    v1 is no longer maintained and is removed in Docker 29.x images."
+  - "Remove `--compatibility` flags from all Compose invocations; the flag was
+    deprecated and is removed in Compose 2.40.x."
+  - "Subscribe to `actions/runner-images` announcements to get advance notice of
+    Docker version bumps before they land on hosted runners."
+  - "Pin Docker Compose file format version at `version: '3.8'` or later; v2 Compose
+    files have better compatibility with modern Compose plugin versions."
+  - "Test workflows in a local Docker 29.x environment before relying on them in CI
+    to catch API and behavioral differences early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13474"
+    label: "Announcement: Docker 29.1 + Compose 2.40.3 update (runner-images#13474)"
+  - url: "https://github.com/actions/runner-images/issues/14105"
+    label: "Tracking: Ubuntu Docker v29 rollback and re-attempt (runner-images#14105)"
+  - url: "https://docs.docker.com/compose/releases/migrate/"
+    label: "Docker Docs: Migrate from Compose v1 to v2"
+  - url: "https://docs.docker.com/engine/release-notes/29.1/"
+    label: "Docker Engine 29.1 release notes"

package/errors/runner-environment/node-20-toolcache-removal.yml

@@ -0,0 +1,134 @@
+id: runner-environment-029
+title: "Node.js 20 Removed from Runner Image Toolcache — Scripts Break Without setup-node"
+category: runner-environment
+severity: error
+tags:
+  - node
+  - nodejs
+  - toolcache
+  - node20
+  - node22
+  - setup-node
+  - eol
+patterns:
+  - regex: "node.*not found|node: command not found"
+    flags: "i"
+  - regex: "node.*version.*20.*not.*available|node 20.*removed"
+    flags: "i"
+  - regex: "required node.*20|node@20.*not installed"
+    flags: "i"
+  - regex: "engines.*node.*20.*not satisfied"
+    flags: "i"
+error_messages:
+  - "node: command not found"
+  - "The tool 'node' for version spec '20' was not found locally."
+  - "Couldn't resolve the package 'node' to a version matching '20'"
+  - "error engines: The engine \"node\" is incompatible with this module."
+root_cause: |
+  Node.js 20 reached **end-of-life on April 30, 2026**. Starting with runner image
+  releases on **May 18, 2026** (commit 249562679f on actions/runner-images), Node.js 20
+  was removed from the pre-installed toolcache on all runner images (Ubuntu, macOS,
+  Windows).
+
+  **What changed:**
+  - The default system `node` binary on all runner images changed from Node.js **20**
+    to Node.js **22** (Maintenance LTS).
+  - `node 20` is no longer available in the toolcache — `actions/setup-node` will
+    download it from the internet if explicitly requested, or fail if the network is
+    not available (self-hosted runners with restricted network access).
+  - Workflows that use `node` without `actions/setup-node` now get Node 22 by default.
+
+  **Three distinct breakage patterns:**
+
+  1. **Shell scripts calling `node script.js`** — these now run under Node 22, which
+     may break code that relied on Node 20 behavior (e.g., `fetch` API differences,
+     removed experimental APIs, `--openssl-legacy-provider` not available by default).
+
+  2. **`actions/setup-node` without version** — previously defaulted to node-version-
+     file lookup or the installed 20.x; now defaults to the latest LTS (22.x). Any
+     `package.json` `engines` field restricting to `>=20 <21` still works, but strict
+     `20.x` pins will now cause download overhead or failure.
+
+  3. **Self-hosted runners with restricted internet access** — if a workflow requests
+     `node-version: '20'` via `actions/setup-node` and the runner has no internet
+     access to download from nodejs.org, the setup step fails because 20 is no longer
+     in the local toolcache.
+
+  Note: This is distinct from the **action runtime migration** (Node 20 → Node 24 for
+  running JavaScript actions themselves, announced separately). This entry covers the
+  *pre-installed Node.js available to shell scripts*.
+fix: |
+  Update workflows to use Node.js 22 (current Maintenance LTS) or pin an explicit LTS
+  version via `actions/setup-node`.
+
+  **Option 1 — Explicit version pin (recommended for reproducibility):**
+  Add `actions/setup-node` with an explicit `node-version` or `node-version-file`.
+
+  **Option 2 — Use `.nvmrc` or `.node-version` file:**
+  Create a version file in the repo root and use `node-version-file` input.
+
+  **Option 3 — Accept Node 22:**
+  Test your application on Node 22 and update `package.json` `engines` accordingly.
+
+  **For self-hosted runners with no internet:**
+  Pre-install Node.js 22 in the runner's local toolcache directory and point
+  `AGENT_TOOLSDIRECTORY` to it.
+fix_code:
+  - language: yaml
+    label: "Pin explicit Node.js version via actions/setup-node"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'   # or '20' to keep on 20 (downloaded from web)
+                cache: 'npm'
+            - run: npm ci
+            - run: npm test
+  - language: yaml
+    label: "Use .nvmrc to declare Node version in the repo"
+    code: |
+      # .nvmrc (in repo root)
+      # 22
+
+      # workflow step
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: "Matrix build to verify compatibility across Node versions"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              node-version: ['20', '22', '24']
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node-version }}
+            - run: npm ci && npm test
+prevention:
+  - "Always use `actions/setup-node` with an explicit `node-version` or
+    `node-version-file` — never rely on the runner's pre-installed Node.js version."
+  - "Add a `.nvmrc` or `.node-version` file to your repository to pin Node.js version
+    for local dev, CI, and Vercel/Netlify deployments simultaneously."
+  - "Watch for Node.js EOL dates at https://github.com/nodejs/release#readme — plan
+    upgrades before the runner image drops the EOL version."
+  - "For self-hosted runners, maintain a local toolcache refresh process whenever a
+    new Node.js LTS is released or an old one reaches EOL."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14029"
+    label: "Announcement: Node.js 20 removal from runner images (runner-images#14029)"
+  - url: "https://github.com/nodejs/release#readme"
+    label: "Node.js Release Schedule — EOL dates"
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node — official action documentation"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/customizing-github-hosted-runners"
+    label: "GitHub Docs: Customizing GitHub-hosted runners"

package/errors/runner-environment/ubuntu-arm64-docker-not-preinstalled.yml

@@ -0,0 +1,137 @@
+id: runner-environment-030
+title: "Ubuntu ARM64 Runner Missing Docker — docker: command not found on arm64"
+category: runner-environment
+severity: error
+tags:
+  - arm64
+  - aarch64
+  - docker
+  - ubuntu
+  - partner-runner
+  - docker-buildx
+  - setup-buildx-action
+patterns:
+  - regex: "docker.*command not found|docker.*not found.*arm64"
+    flags: "i"
+  - regex: "docker/setup-buildx-action.*error|setup-buildx.*arm64.*fail"
+    flags: "i"
+  - regex: "Cannot connect to the Docker daemon|Is the docker daemon running"
+    flags: "i"
+  - regex: "Error: Unable to locate executable file: docker"
+    flags: "i"
+error_messages:
+  - "docker: command not found"
+  - "Error: Unable to locate executable file: docker"
+  - "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"
+  - "exec: \"docker\": executable file not found in $PATH"
+root_cause: |
+  GitHub-hosted **Ubuntu 24.04 ARM64** runner images (available via labels such as
+  `ubuntu-24.04-arm64`, `ubuntu-arm`, or partner runner images for ARM64) do **not**
+  have Docker pre-installed on `PATH`, despite the partner image README listing Docker
+  client and server versions.
+
+  This is a **documentation mismatch** affecting ARM64 runner users (actions/runner-
+  images#14051, created March 2026, still open as of May 2026):
+  - The `partner-runner-images` README lists Docker Client 28.0.4 and Docker Server
+    28.0.4 as installed software.
+  - In practice, `docker` is **not present on `PATH`** in these runners.
+  - The runner is identified as `Source: Partner` and `Base Image for Ubuntu Server
+    24.04`.
+
+  **Affected workflows:**
+  - Any step using `docker build`, `docker run`, `docker pull`, or `docker push`
+    directly in a `run:` block.
+  - `docker/setup-buildx-action@v3` fails because it cannot find the Docker CLI.
+  - Container-based jobs that use the host Docker socket.
+  - Multi-platform builds that need BuildKit on ARM64.
+
+  **x86-64 runners are not affected.** This is specific to ARM64 GitHub-hosted
+  runners using the partner image.
+
+  This is distinct from the `docker-buildx-not-setup.yml` entry (which covers x64
+  runners where Docker BuildKit is present but `buildx` is not configured).
+fix: |
+  Install Docker explicitly at the start of ARM64 workflow jobs, or use a Docker
+  action that handles installation automatically.
+
+  **Option 1 — Install Docker via the official convenience script (fastest):**
+  Run the Docker install script at the start of the job. This adds ~60 seconds to
+  job start time but ensures Docker is available.
+
+  **Option 2 — Use `docker/setup-buildx-action@v3` after Docker install:**
+  After installing Docker, `setup-buildx-action` can then install BuildKit buildx.
+
+  **Option 3 — Use a Docker-pre-installed large runner:**
+  If budget allows, use GitHub's x86-64 larger runners which have Docker pre-installed,
+  or a self-hosted ARM64 runner with Docker pre-configured.
+
+  **Option 4 — Use `runs-on: ubuntu-latest` (x86-64) instead of ARM64:**
+  If ARM64 is not strictly required, run on x86-64 which has Docker pre-installed.
+fix_code:
+  - language: yaml
+    label: "Install Docker on ARM64 runner before using it"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm64
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Docker
+              run: |
+                curl -fsSL https://get.docker.com -o get-docker.sh
+                sudo sh get-docker.sh
+                sudo usermod -aG docker $USER
+                sudo systemctl start docker
+                docker --version
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Build image
+              run: docker build -t myapp:latest .
+  - language: yaml
+    label: "Cross-platform build with explicit ARM64 Docker install"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - runner: ubuntu-latest
+                  platform: linux/amd64
+                - runner: ubuntu-24.04-arm64
+                  platform: linux/arm64
+                  install_docker: true
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Docker (ARM64 only)
+              if: matrix.install_docker == true
+              run: |
+                curl -fsSL https://get.docker.com | sudo sh
+                sudo usermod -aG docker $USER
+                sudo systemctl enable --now docker
+
+            - name: Build for ${{ matrix.platform }}
+              run: docker build --platform ${{ matrix.platform }} -t myapp .
+prevention:
+  - "Before adding `runs-on: ubuntu-24.04-arm64` to a workflow that uses Docker,
+    verify Docker availability by running `docker --version` in a test job."
+  - "Check the current partner runner image README at
+    https://github.com/actions/partner-runner-images before relying on pre-installed
+    tooling on non-standard runner images."
+  - "Consider using self-hosted ARM64 runners with Docker pre-configured for
+    production workloads that depend on Docker on ARM64."
+  - "Track the open issue (actions/runner-images#14051) for when GitHub adds Docker
+    to ARM64 partner images natively."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14051"
+    label: "Issue: Ubuntu 24.04 ARM64 missing Docker (runner-images#14051)"
+  - url: "https://github.com/actions/partner-runner-images"
+    label: "actions/partner-runner-images — partner runner image definitions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "GitHub Docs: GitHub-hosted runner specifications"
+  - url: "https://docs.docker.com/engine/install/ubuntu/"
+    label: "Docker Docs: Install Docker Engine on Ubuntu"

package/errors/runner-environment/windows-2019-runner-retirement.yml

@@ -0,0 +1,100 @@
+id: runner-environment-028
+title: "windows-2019 Runner Retired — Jobs Fail with No Runner Found"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-2019
+  - runner-retirement
+  - deprecation
+  - runs-on
+  - migration
+patterns:
+  - regex: "No runner matching the requested labels.*windows-2019"
+    flags: "i"
+  - regex: "Could not find any runner matching.*windows-2019"
+    flags: "i"
+  - regex: "windows-2019.*is no longer supported"
+    flags: "i"
+  - regex: "windows-2019.*deprecated.*unsupported"
+    flags: "i"
+error_messages:
+  - "No runner matching the requested labels was found: windows-2019"
+  - "Could not find any runner matching the requested labels: [windows-2019]"
+  - "This request was automatically failed because 'windows-2019' is no longer available."
+root_cause: |
+  GitHub retired the `windows-2019` runner image on **June 30, 2025** following the
+  GitHub Actions N-1 OS support policy (only the latest two major versions of each OS
+  are hosted).
+
+  **Timeline:**
+  - **2025-04-15**: Deprecation announcement (actions/runner-images#12045)
+  - **2025-06-01**: Deprecation begins — longer queue times during peak hours
+  - **Between June 1–30**: GitHub temporarily fails jobs using `windows-2019` to raise
+    awareness in advance of the hard removal
+  - **2025-06-30**: `windows-2019` fully unsupported — all jobs using this label fail
+
+  Workflows that explicitly specify `runs-on: windows-2019` (or any combination like
+  `[self-hosted, windows-2019]` on non-self-hosted runners) will fail immediately after
+  the retirement date. Workflows that used `windows-latest` were not affected since
+  `windows-latest` already pointed to `windows-2022`.
+
+  The replacement is `windows-2022` (already the current `windows-latest` at time of
+  retirement) or `windows-2025` (Windows Server 2025 image).
+fix: |
+  Update all `runs-on` references from `windows-2019` to `windows-2022` or
+  `windows-2025` (or use `windows-latest`).
+
+  **Migration path:**
+  - `windows-2019` → `windows-2022` (minimal change, widely compatible)
+  - `windows-2019` → `windows-2025` (latest; check for VS 2026 path changes if using
+    hardcoded MSVC paths)
+  - `windows-2019` → `windows-latest` (tracks latest, reduces future manual migrations)
+
+  **Before migrating**, verify that your workflow does not depend on Windows Server 2019
+  -specific behavior such as:
+  - VS 2019 toolchain at `C:\Program Files (x86)\Microsoft Visual Studio\2019\`
+  - Older .NET Framework SDK versions not present on 2022 or 2025 images
+  - Windows Server 2019-specific APIs or registry keys
+fix_code:
+  - language: yaml
+    label: "Replace windows-2019 with windows-2022"
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: windows-2019
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: msbuild MyApp.sln /p:Configuration=Release
+  - language: yaml
+    label: "Use windows-latest to avoid future manual migrations"
+    code: |
+      jobs:
+        build:
+          # windows-latest currently points to windows-2025 (as of June 2026)
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: bash
+    label: "Audit all workflows for windows-2019 references"
+    code: |
+      # Find all workflow files using windows-2019
+      grep -r "windows-2019" .github/workflows/
+prevention:
+  - "Use `windows-latest` instead of pinned OS versions unless you have a specific
+    reason to pin. This avoids retirement failures entirely."
+  - "Subscribe to the `actions/runner-images` repository announcements to receive
+    deprecation notices before they become hard failures."
+  - "When you must pin an OS version, add a calendar reminder or Renovate/Dependabot
+    rule to review the pin when the N-1 policy applies."
+  - "Run a periodic repository search for retired runner labels:
+    `grep -r 'windows-2019\\|ubuntu-20.04\\|macos-12' .github/workflows/`"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12045"
+    label: "Announcement: Windows 2019 deprecation and retirement (runner-images#12045)"
+  - url: "https://github.blog/changelog/2025-04-15-upcoming-breaking-changes-and-releases-for-github-actions/"
+    label: "GitHub Changelog: Windows Server 2019 is closing down"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs: Supported GitHub-hosted runners"

package/errors/silent-failures/upload-artifact-v4-hidden-files-excluded.yml

@@ -0,0 +1,121 @@
+id: silent-failures-012
+title: "upload-artifact v4.4.0 Silently Excludes Hidden Files and Directories"
+category: silent-failures
+severity: silent-failure
+tags:
+  - upload-artifact
+  - artifact-v4
+  - hidden-files
+  - dotfiles
+  - path-patterns
+  - silent
+patterns:
+  - regex: "upload.*artifact.*no files.*found|artifact.*upload.*0.*bytes"
+    flags: "i"
+  - regex: "Artifact.*successfully uploaded.*0 files|uploaded 0 item"
+    flags: "i"
+  - regex: "include-hidden-files"
+    flags: "i"
+error_messages:
+  - "Warning: No files were found with the provided path: .env.dist"
+  - "Artifact upload: 0 items, 0 bytes"
+  - "With the provided path, there will be 0 files uploaded"
+  - "Uploaded artifact 'dotfiles' (0 bytes)"
+root_cause: |
+  Starting with **actions/upload-artifact v4.4.0** (released February 2026), the action
+  excludes files and directories whose names begin with `.` (dot/hidden files) **by
+  default**. This is a **silent behavior change** — the upload action still reports
+  "success" but skips all dotfiles, resulting in an artifact that is missing expected
+  content without any error or warning in most cases.
+
+  **Files and directories affected:**
+  - `.env`, `.env.dist`, `.env.example`, `.env.test`
+  - `.gitignore`, `.gitattributes`, `.eslintrc`, `.prettierrc`
+  - `.docker/`, `.github/`, `.cache/`, `.npm/`
+  - Any file or directory with a name starting with `.`
+
+  **Why this is a silent failure:** The action reports "Artifact uploaded successfully"
+  even when all matched files happen to be hidden files and thus are excluded. In cases
+  where the path glob matches only hidden files, the artifact is created with 0 bytes
+  and no error is thrown. Downstream jobs that download and use the artifact will
+  receive an empty directory or encounter missing file errors, far from the upload step.
+
+  **Historical context:** This change was introduced for security consistency —
+  dotfiles often contain secrets (`.env`), credentials, or sensitive configuration that
+  developers might accidentally expose through artifacts. The default exclusion prevents
+  accidental secret leakage via artifacts.
+fix: |
+  Set `include-hidden-files: true` on the `upload-artifact` step to restore the
+  previous behavior and include dotfiles in the artifact.
+
+  **Security note:** Before enabling `include-hidden-files: true`, review whether
+  the files being uploaded contain secrets. Consider using GitHub secrets or environment
+  variables for sensitive values rather than uploading `.env` files as artifacts.
+
+  Alternatively, rename configuration files to not start with `.` if they don't
+  contain sensitive values (e.g., `env.example` instead of `.env.example`).
+fix_code:
+  - language: yaml
+    label: "Enable hidden file inclusion with include-hidden-files"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            # ❌ v4.4.0+: .env.dist, .config/, etc. are silently excluded
+            # - uses: actions/upload-artifact@v4
+            #   with:
+            #     name: build-output
+            #     path: dist/
+
+            # ✅ Explicitly include hidden files when needed
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+                include-hidden-files: true  # restores pre-v4.4.0 behavior
+  - language: yaml
+    label: "Targeted upload — avoid hidden files where possible"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            # ✅ Better: upload specific file types, not entire directories
+            # This avoids accidentally including or excluding hidden files
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-artifacts
+                path: |
+                  dist/**/*.js
+                  dist/**/*.css
+                  dist/**/*.html
+                  env.example   # renamed from .env.example to avoid hiding
+prevention:
+  - "Audit workflows that upload artifacts containing dotfiles (`.env.*`, `.config`,
+    `.cache/`) — add `include-hidden-files: true` explicitly if those files are needed."
+  - "Check artifact sizes after upgrading to v4.4.0+: a 0-byte or unexpectedly small
+    artifact often indicates hidden files were silently excluded."
+  - "For environment template files that should be shared as artifacts, rename them
+    to not start with `.` (e.g., `env.template` instead of `.env.template`)."
+  - "Never upload actual `.env` files with real secrets as artifacts — use GitHub
+    secrets or OIDC-based secret retrieval instead."
+docs:
+  - url: "https://stackoverflow.com/questions/78941839/github-actions-upload-artifactv4-4-0-path-patterns-not-working-after-upgrade"
+    label: "Stack Overflow: upload-artifact v4.4.0 path patterns not working (hidden files)"
+  - url: "https://github.blog/changelog/2026-02-26-github-actions-now-supports-uploading-and-downloading-non-zipped-artifacts"
+    label: "GitHub Changelog: artifact upload/download improvements (Feb 2026)"
+  - url: "https://github.com/actions/upload-artifact/blob/main/RELEASES.md"
+    label: "upload-artifact v4 release notes"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "GitHub Docs: Storing and sharing data from a workflow"

package/errors/yaml-syntax/vars-context-rejected-composite-actions.yml

@@ -0,0 +1,127 @@
+id: yaml-syntax-016
+title: "vars Context Rejected Inside Composite Action Expressions"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-actions
+  - vars-context
+  - expression
+  - runner-validation
+  - organization-variables
+  - repository-variables
+patterns:
+  - regex: "Unrecognized named-value.*'?vars'?"
+    flags: "i"
+  - regex: "Unexpected value.*vars\\.\\w+"
+    flags: "i"
+  - regex: "inputs\\.\\w+.*\\|\\|.*vars\\.\\w+.*not.*recognized"
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'vars'. Located at position X within expression: inputs.region || vars.AWS_REGION || 'us-east-1'"
+  - "Error: Unrecognized named-value: 'vars'"
+  - "Invalid workflow file: .github/actions/my-action/action.yml (Line N, Col M): Unrecognized named-value: 'vars'"
+root_cause: |
+  The `vars` context (organization/repository/environment variables) is **not available
+  inside composite action definitions** (`action.yml`). Runner validation enforces
+  context availability rules per the element type, and composite actions are not
+  permitted to reference `vars.*` in their step expressions.
+
+  This was not always enforced — older runner versions allowed some cross-context
+  references in composite actions, but a runner validation tightening (tracked in
+  actions/runner#4311) made this a hard error. Workflows that worked before started
+  failing after runner updates were rolled out to GitHub-hosted and self-hosted runners.
+
+  **Why the restriction exists:** Composite actions are designed to be reusable across
+  repositories and organizations. The `vars` context is scoped to the calling repository
+  or organization — a composite action cannot safely resolve `vars.*` at definition time
+  because it would create an implicit dependency on the caller's variable set without
+  explicit declaration as an `input`.
+
+  **Affected expression positions:**
+  - `with:` value fields in composite action steps
+  - `run:` shell commands using `${{ vars.* }}` syntax
+  - `if:` conditions on composite action steps
+  - Default values for composite action inputs that fall back to `vars.*`
+fix: |
+  Remove `vars.*` references from composite action definitions. Instead, require
+  callers to pass variables explicitly as action `inputs`, and reference those inputs
+  inside the composite action.
+
+  **Pattern:**
+  1. Add an explicit `input` to the composite action for any value currently read from
+     `vars.*`
+  2. Give it a meaningful name and a default value (empty string or a sensible default)
+  3. In the calling workflow, pass the variable value as `with: my-input: ${{ vars.MY_VAR }}`
+  4. Inside the composite action, replace `${{ vars.MY_VAR }}` with `${{ inputs.my-input }}`
+fix_code:
+  - language: yaml
+    label: "action.yml — Replace vars.* with an explicit input"
+    code: |
+      # ❌ BROKEN: vars context not available in composite actions
+      # action.yml
+      inputs:
+        region:
+          description: "AWS region"
+          required: false
+          default: ""   # cannot use: ${{ vars.AWS_REGION }}
+
+      runs:
+        using: composite
+        steps:
+          - name: Deploy
+            shell: bash
+            run: |
+              # ❌ This will fail:
+              # REGION="${{ inputs.region || vars.AWS_REGION || 'us-east-1' }}"
+
+              # ✅ Use only inputs:
+              REGION="${{ inputs.region || 'us-east-1' }}"
+              echo "Deploying to $REGION"
+  - language: yaml
+    label: "caller workflow — Pass vars.* as an explicit input"
+    code: |
+      # ✅ Calling workflow passes vars.* to the composite action explicitly
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/deploy
+              with:
+                region: ${{ vars.AWS_REGION }}   # resolved in caller, not inside composite
+  - language: yaml
+    label: "action.yml — Full corrected composite action"
+    code: |
+      # ✅ CORRECT: composite action with explicit input, no vars.* reference
+      name: Deploy to AWS
+      description: Deploy application to AWS
+
+      inputs:
+        region:
+          description: "AWS region (pass vars.AWS_REGION from caller)"
+          required: false
+          default: "us-east-1"
+
+      runs:
+        using: composite
+        steps:
+          - name: Deploy
+            shell: bash
+            run: echo "Deploying to ${{ inputs.region }}"
+prevention:
+  - "Never reference `vars.*`, `secrets.*`, or `env.*` directly inside composite action
+    step expressions — these contexts are not available at composite action evaluation time."
+  - "Treat composite actions like reusable library functions: all runtime values must
+    come in through declared `inputs`."
+  - "In the calling workflow, resolve `vars.*` or `secrets.*` at the `with:` level and
+    pass resulting values as string inputs."
+  - "Run `act` locally or validate with `actionlint` to catch context availability
+    errors before pushing to GitHub."
+docs:
+  - url: "https://github.com/actions/runner/issues/4311"
+    label: "actions/runner#4311 — vars context rejected in composite actions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "GitHub Docs: Context availability by element type"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/variables#using-the-vars-context-to-access-configuration-variable-values"
+    label: "GitHub Docs: Using the vars context"

package/package.json

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