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