@htekdev/actions-debugger 1.0.8 → 1.0.10

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/permissions-auth/deploy-pages-missing-permissions.yml

@@ -0,0 +1,144 @@
+id: permissions-auth-009
+title: "actions/deploy-pages Fails 403 — Missing pages: write or id-token: write Permissions"
+category: permissions-auth
+severity: error
+tags:
+  - deploy-pages
+  - pages
+  - permissions
+  - id-token
+  - oidc
+  - github-token
+  - 403
+patterns:
+  - regex: "Failed to create deployment.*status: 403.*pages: write"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+  - regex: "Fetching artifact metadata failed.*Resource not accessible by integration"
+    flags: "i"
+  - regex: "Error: Error: Failed to create deployment \\(status: 403\\)"
+    flags: "i"
+error_messages:
+  - "Error: Fetching artifact metadata failed. Is githubstatus.com reporting issues with API requests, Pages or Actions? Please re-run the deployment at a later time."
+  - "Error: HttpError: Resource not accessible by integration"
+  - "Error: Error: Failed to create deployment (status: 403) with build version abc123. Ensure GITHUB_TOKEN has permission \"pages: write\"."
+  - "Creating Pages deployment failed"
+root_cause: |
+  `actions/deploy-pages` uses the GitHub Pages REST API, which requires an OIDC-issued
+  JWT token for authentication. This imposes three distinct permissions that must all be
+  present on the **deploy job** (not the build job):
+
+  1. `pages: write` — allows the GITHUB_TOKEN to create and update GitHub Pages deployments.
+  2. `id-token: write` — allows the runner to request an OIDC JWT from GitHub's token
+     endpoint. Without this, `deploy-pages` cannot obtain the token used to authenticate
+     the Pages API call, resulting in the misleading "Resource not accessible by integration"
+     HTTP 403 error.
+  3. `contents: read` — required to read the uploaded artifact. Often already set by
+     inheritance but must be explicit when a workflow-level `permissions:` block restricts
+     all tokens to read-only.
+
+  **Why this is confusing:**
+  - The error message says "Resource not accessible by integration" which looks like a generic
+    API permission problem, not a missing `id-token` scope.
+  - The `pages: write` permission alone is insufficient — `id-token: write` is equally
+    required and its absence produces the exact same error.
+  - Permissions set at the **workflow level** do not automatically apply to jobs that override
+    them. The deploy job must declare its own `permissions:` block.
+  - The artifact upload (via `actions/upload-pages-artifact`) happens in a SEPARATE job from
+    the deploy — permissions for upload and deploy must be set independently.
+
+  **Source:** Confirmed in `actions/deploy-pages` issues #285, #286 (Dec 2023) — over 16
+  reactions and widespread community impact.
+fix: |
+  Add all three required permissions to the deploy job. The build job that runs
+  `upload-pages-artifact` does not need these permissions, but the deploy job does.
+
+  Also verify that GitHub Pages is enabled for the repository under
+  Settings → Pages → Source → "GitHub Actions".
+fix_code:
+  - language: yaml
+    label: "Correct two-job Pages deployment workflow with required permissions"
+    code: |
+      name: Deploy GitHub Pages
+
+      on:
+        push:
+          branches: [main]
+
+      # Deny all permissions at workflow level; grant explicitly per job
+      permissions:
+        contents: read
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build site
+              run: npm run build   # outputs to ./dist
+
+            - name: Upload Pages artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                path: ./dist
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          permissions:
+            pages: write        # ← Required: create/update Pages deployment
+            id-token: write     # ← Required: obtain OIDC JWT for Pages API auth
+            contents: read      # ← Required: read the uploaded artifact
+          environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+          steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4
+  - language: yaml
+    label: "Single-job variant — all permissions in one job"
+    code: |
+      name: Deploy Pages (single job)
+
+      on:
+        push:
+          branches: [main]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            pages: write
+            id-token: write
+            contents: read
+          environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - uses: actions/upload-pages-artifact@v3
+              with:
+                path: ./dist
+            - id: deployment
+              uses: actions/deploy-pages@v4
+prevention:
+  - "Always set `pages: write`, `id-token: write`, and `contents: read` on the deploy job — not the build job and not only at the workflow level."
+  - "Confirm GitHub Pages is enabled under repository Settings → Pages → Source → 'GitHub Actions' before running the workflow."
+  - "When using a workflow-level `permissions:` block that restricts defaults, remember job-level permissions do not inherit write scopes — they must be re-declared."
+  - "The `environment: github-pages` block is required for the Pages API to create a deployment — do not omit it."
+docs:
+  - url: "https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow"
+    label: "GitHub Docs: Publishing GitHub Pages with Actions"
+  - url: "https://github.com/actions/deploy-pages"
+    label: "actions/deploy-pages — official action repository"
+  - url: "https://github.com/actions/deploy-pages/issues/285"
+    label: "actions/deploy-pages #285: Failing to fetch artifact metadata since 4.0.0"
+  - url: "https://github.com/actions/deploy-pages/issues/286"
+    label: "actions/deploy-pages #286: Bump to V4 broke the deploy step"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
+    label: "GitHub Docs: Security hardening with OpenID Connect"

package/errors/permissions-auth/fine-grained-pat-actions-scope-missing.yml

@@ -0,0 +1,128 @@
+id: permissions-auth-010
+title: "Fine-Grained PAT Missing Actions Permission — Workflow Dispatch and API Calls Fail 403"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - pat
+  - personal-access-token
+  - actions
+  - workflow-dispatch
+  - 403
+  - api
+patterns:
+  - regex: "HTTP 403.*fine.?grained.*token"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+  - regex: "Must have admin rights to Repository\\."
+    flags: "i"
+  - regex: "403.*workflow.*dispatch"
+    flags: "i"
+error_messages:
+  - "HTTP 403: {\"message\":\"Resource not accessible by integration\",\"documentation_url\":\"https://docs.github.com/rest/actions/workflows\"}"
+  - "Error: error making HTTP request: 403 Resource not accessible by integration"
+  - "gh: Could not run workflow: HTTP 422 Unprocessable Entity"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+root_cause: |
+  GitHub fine-grained personal access tokens (introduced 2022, GA 2023) do NOT include
+  the "Actions" permission scope by default when created. This is different from classic
+  PATs where the `repo` scope implicitly granted access to Actions APIs.
+
+  When a fine-grained PAT is used to:
+  - Trigger workflows via REST API (`POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)
+  - List or cancel workflow runs
+  - Download workflow run logs
+  - Use `gh workflow run` / `gh run list` with the PAT as `GH_TOKEN`
+
+  ...the API returns HTTP 403 "Resource not accessible by integration" because the
+  fine-grained token lacks the explicit `Actions: read` or `Actions: write` permission.
+
+  **Why this affects more users over time:**
+  - GitHub is progressively deprecating classic PATs in favor of fine-grained PATs.
+  - Organization policies can require fine-grained PATs only, blocking classic PAT usage.
+  - Automation pipelines that worked with classic `repo`-scoped PATs silently break when
+    migrated to fine-grained PATs if the Actions permission is not explicitly added.
+  - The error message "Resource not accessible by integration" is the same as the one
+    shown for missing `GITHUB_TOKEN` scopes, making diagnosis harder.
+
+  **Required permissions on the fine-grained PAT by use case:**
+  | Use case | Required permission |
+  |---|---|
+  | Trigger workflow (`workflow_dispatch`) | Actions: write |
+  | Cancel / re-run workflow run | Actions: write |
+  | List workflow runs / jobs | Actions: read |
+  | Download workflow run logs | Actions: read |
+  | Read workflow YAML definitions | Actions: read |
+fix: |
+  Regenerate or edit the fine-grained PAT and add the **Actions** permission with the
+  appropriate access level:
+
+  - **Read-only** — for listing runs, reading logs, checking run status.
+  - **Read and write** — for dispatching workflows, cancelling runs, re-triggering jobs.
+
+  Navigate to: GitHub → Settings → Developer Settings → Personal access tokens →
+  Fine-grained tokens → (select token) → Permissions → Repository permissions →
+  Actions → set to "Read and write".
+
+  If the repository is in an organization, also ensure the organization has not restricted
+  fine-grained PAT usage to specific resources that exclude this repository.
+fix_code:
+  - language: yaml
+    label: "Using a fine-grained PAT with Actions permission to trigger a workflow"
+    code: |
+      # Store the fine-grained PAT as a repository secret: DEPLOY_PAT
+      # The PAT must have: Actions: write, Contents: read (minimum)
+
+      name: Trigger Deployment
+
+      on:
+        workflow_dispatch:
+
+      jobs:
+        trigger:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Dispatch downstream workflow
+              run: |
+                gh workflow run deploy.yml \
+                  -f environment=production \
+                  --repo org/downstream-repo
+              env:
+                GH_TOKEN: ${{ secrets.DEPLOY_PAT }}   # Fine-grained PAT with Actions: write
+  - language: yaml
+    label: "Required PAT permissions checklist for common Actions API uses"
+    code: |
+      # Fine-grained PAT permission requirements:
+      #
+      # Trigger workflow dispatch      → Actions: Write
+      # Cancel a workflow run          → Actions: Write
+      # Re-run failed jobs             → Actions: Write
+      # List workflow runs             → Actions: Read
+      # Download run logs              → Actions: Read
+      # Get workflow definition        → Actions: Read
+      # Approve environment deployment → Actions: Write + Environments: Write
+      #
+      # Classic PAT 'repo' scope covers all of the above implicitly.
+      # Fine-grained PATs require explicit opt-in per permission category.
+
+      # To check if your PAT has the right permissions:
+      - name: Verify PAT has Actions permission
+        run: |
+          gh api /repos/${{ github.repository }}/actions/workflows \
+            --jq '.total_count'
+        env:
+          GH_TOKEN: ${{ secrets.DEPLOY_PAT }}   # Returns 403 if Actions: read is missing
+prevention:
+  - "When migrating from classic PATs to fine-grained PATs, explicitly audit which permission categories the classic `repo` scope was implicitly covering and add each one."
+  - "Add `Actions: read` at minimum to any fine-grained PAT that will be used in GitHub Actions pipelines, even for read-only operations."
+  - "Store fine-grained PATs as org-level or repository secrets and add a comment documenting which permissions the PAT requires."
+  - "Use a dedicated machine account (bot user) for automation PATs so permissions can be audited independently of individual developer accounts."
+  - "If an organization policy requires fine-grained PATs, update all automation onboarding docs to include the Actions permission explicitly."
+docs:
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "GitHub Docs: Creating a fine-grained personal access token"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "REST API: Create a workflow dispatch event"
+  - url: "https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization"
+    label: "GitHub Docs: PAT policy for organizations"

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/triggers/repository-dispatch-event-type-mismatch.yml

@@ -0,0 +1,116 @@
+id: triggers-010
+title: "repository_dispatch Event Type Not in types: Filter — Workflow Silently Skipped"
+category: triggers
+severity: silent-failure
+tags:
+  - repository_dispatch
+  - event-type
+  - types-filter
+  - triggers
+  - api
+  - silent
+patterns:
+  - regex: "repository_dispatch"
+    flags: "i"
+  - regex: "types:\\s*\\[.*\\]"
+    flags: "i"
+  - regex: "client_payload"
+    flags: "i"
+error_messages:
+  - "No runs found for workflow"
+  - "Workflow not triggered by repository_dispatch event"
+root_cause: |
+  A `repository_dispatch` workflow only fires when the dispatched `event_type` value
+  matches one of the values in the `types:` filter. If the event type sent via the API
+  does not match, GitHub silently drops it — no error, no notification, the workflow simply
+  never starts.
+
+  **Common failure scenarios:**
+
+  1. **Typo or case mismatch**: `event_type: "Deploy_Staging"` dispatched but workflow
+     has `types: [deploy_staging]` (underscore vs case sensitivity). Event types are
+     case-sensitive.
+
+  2. **Omitting the types: filter entirely — workflow fires for ALL events** (opposite
+     problem): Without a `types:` filter, the workflow runs for every `repository_dispatch`
+     event, including internal automation events not intended to trigger it.
+
+  3. **API payload uses wrong field name**: The REST API requires the `event_type` field
+     under the JSON body. Some clients accidentally nest it differently or omit it entirely,
+     causing the dispatch to use the default empty event type which matches nothing.
+
+  4. **Cross-workflow automation chain**: Workflow A dispatches event type `build-complete`.
+     Workflow B listens for `build_complete` (underscore). The chain silently breaks with no
+     logs in either workflow.
+
+  **API payload shape:**
+  ```
+  POST /repos/{owner}/{repo}/dispatches
+  {
+    "event_type": "deploy_staging",       ← Must exactly match types: filter
+    "client_payload": { ... }
+  }
+  ```
+fix: |
+  Verify that the `event_type` string in the API POST body matches exactly (case-sensitive)
+  one of the values declared in the workflow's `types:` filter.
+
+  To debug: add a catch-all workflow with no `types:` filter (matches all repository_dispatch
+  events) to confirm the event is arriving at all, then compare the `github.event.action`
+  value to what your workflow expects.
+fix_code:
+  - language: yaml
+    label: "Workflow with correctly declared repository_dispatch types filter"
+    code: |
+      on:
+        repository_dispatch:
+          types:
+            - deploy_staging        # ← Must match event_type exactly (case-sensitive)
+            - deploy_production
+            - run_smoke_tests
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Show dispatched event
+              run: |
+                echo "Event: ${{ github.event.action }}"
+                echo "Payload: ${{ toJSON(github.event.client_payload) }}"
+  - language: yaml
+    label: "Debugging workflow — catch ALL repository_dispatch events"
+    code: |
+      # Temporarily add this workflow to diagnose missing dispatches
+      on:
+        repository_dispatch:    # No types: filter = receives everything
+
+      jobs:
+        debug:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Log event details
+              run: |
+                echo "event_type / action: ${{ github.event.action }}"
+                echo "client_payload: ${{ toJSON(github.event.client_payload) }}"
+  - language: yaml
+    label: "Dispatching via REST API — correct payload structure"
+    code: |
+      # Using gh api to dispatch correctly
+      gh api \
+        --method POST \
+        -H "Accept: application/vnd.github+json" \
+        /repos/ORG/REPO/dispatches \
+        -f event_type="deploy_staging" \      # ← Matches types: [deploy_staging]
+        -F client_payload='{"version":"v1.2.3","env":"staging"}'
+prevention:
+  - "Treat `event_type` values as constants — define them in a shared location (e.g., a constants file or workflow comment) used by both the dispatcher and the listener."
+  - "Add an `echo` step that logs `github.event.action` at the start of every repository_dispatch workflow to confirm the correct event type was received."
+  - "Use a catch-all debug workflow (no `types:` filter) when setting up a new dispatch chain for the first time."
+  - "Avoid changing event type strings in active automation chains — add new types instead of renaming existing ones."
+  - "Event types are case-sensitive — stick to snake_case by convention to avoid case mismatch bugs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch"
+    label: "GitHub Actions: repository_dispatch event"
+  - url: "https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event"
+    label: "REST API: Create a repository dispatch event"

package/errors/triggers/workflow-call-required-input-not-supplied.yml

@@ -0,0 +1,115 @@
+id: triggers-009
+title: "Reusable Workflow Required Input Not Supplied — workflow_call Fails at Runtime"
+category: triggers
+severity: error
+tags:
+  - workflow_call
+  - reusable-workflow
+  - inputs
+  - required
+  - validation
+  - caller
+patterns:
+  - regex: "Input required and not supplied:\\s*\\w+"
+    flags: "i"
+  - regex: "Required input '\\w+' not provided"
+    flags: "i"
+  - regex: "Error: Input required and not supplied"
+    flags: "i"
+error_messages:
+  - "Error: Input required and not supplied: deploy_env"
+  - "Input required and not supplied: version"
+  - "Required input 'environment' not provided by caller"
+root_cause: |
+  Unlike `workflow_dispatch` (which treats `required: true` as UI-only), the GitHub Actions
+  runner DOES validate required inputs for `on.workflow_call` reusable workflows. If a caller
+  workflow invokes a reusable workflow without passing a declared required input, the runner
+  emits `Error: Input required and not supplied: {input_name}` and fails the job immediately.
+
+  **Common scenarios:**
+  1. **Adding a required input to an existing reusable workflow** without updating all callers.
+     Callers that worked before immediately break because the new required input is missing.
+
+  2. **Calling a reusable workflow from a matrix job** where one matrix variation doesn't
+     apply the needed input conditionally.
+
+  3. **Caller passes the input only under certain conditions** (via `if:`) — when the condition
+     is false, the input is omitted entirely rather than being passed as an empty string.
+
+  4. **Typo in the input name** — caller passes `deploy-env` but the reusable workflow expects
+     `deploy_env` (hyphens vs underscores). The declared input is not satisfied.
+
+  **Note:** The error fires at job evaluation time, not step execution time, so the entire job
+  is skipped rather than reaching the failing step.
+fix: |
+  Ensure every caller workflow passes all required inputs declared in the reusable workflow's
+  `on.workflow_call.inputs` block.
+
+  When adding a new required input to a reusable workflow, update all callers before merging.
+  Use `required: false` with a default value if backward compatibility must be preserved.
+
+  If the input is only sometimes needed, declare it as `required: false` and check it
+  at runtime inside the reusable workflow using an early-exit validation step.
+fix_code:
+  - language: yaml
+    label: "Reusable workflow with required input declaration"
+    code: |
+      # .github/workflows/deploy-reusable.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              description: "Target environment"
+              required: true    # Runner enforces this for all callers
+              type: string
+            version:
+              description: "Version tag"
+              required: false
+              default: "latest"
+              type: string
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh "${{ inputs.environment }}" "${{ inputs.version }}"
+  - language: yaml
+    label: "Caller workflow — always pass all required inputs"
+    code: |
+      # .github/workflows/release.yml
+      on:
+        push:
+          tags: ["v*"]
+
+      jobs:
+        deploy:
+          uses: ./.github/workflows/deploy-reusable.yml
+          with:
+            environment: production   # ✅ Required input provided
+            version: ${{ github.ref_name }}
+  - language: yaml
+    label: "Backward-compatible: change required to optional with default"
+    code: |
+      # When adding new inputs to existing reusable workflows, use required: false
+      # with a default to avoid breaking existing callers.
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              required: true
+              type: string
+            notify_slack:      # New input — safe to add with required: false
+              required: false
+              default: "false"
+              type: string
+prevention:
+  - "When adding a new `required: true` input to a reusable workflow, search all callers with `grep -r 'uses:.*deploy-reusable'` and update them simultaneously."
+  - "Prefer `required: false` with a sensible default when backward compatibility matters — validate the value inside the reusable workflow if needed."
+  - "Use consistent naming conventions (all underscores or all hyphens) for input names to avoid typo-related mismatches between callers and the called workflow."
+  - "Test reusable workflow changes in a draft PR that also updates all callers."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow"
+    label: "GitHub Docs: Inputs in reusable workflows"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_call"
+    label: "GitHub Actions: workflow_call event"

package/errors/triggers/workflow-dispatch-required-input-api-bypass.yml

@@ -0,0 +1,114 @@
+id: triggers-008
+title: "workflow_dispatch required: true Silently Bypassed via REST API"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_dispatch
+  - inputs
+  - required
+  - rest-api
+  - gh-cli
+  - validation
+patterns:
+  - regex: "workflow_dispatch.*inputs.*required.*true"
+    flags: "i"
+  - regex: "inputs\\.\\w+.*==.*''"
+    flags: "i"
+error_messages:
+  - "Input required and not supplied: {input_name}"
+root_cause: |
+  The `required: true` flag on `workflow_dispatch` inputs is enforced **only in the GitHub
+  UI** — it renders the field as mandatory in the "Run workflow" dialog. When a workflow
+  is triggered via the REST API (`POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)
+  or `gh workflow run`, the `required` flag is NOT validated server-side. The workflow is
+  dispatched and runs with the input set to an empty string `""` rather than the declared
+  default or an error.
+
+  This creates a subtle silent failure: developers assume `required: true` prevents invalid
+  automation, but any API caller can trigger the workflow with no inputs at all. Steps that
+  depend on the input receive an empty string without any indication something is wrong.
+
+  **Contrast with `workflow_call` (reusable workflows):** Required inputs on `on.workflow_call`
+  ARE validated by the runner — a missing required input produces `Error: Input required and
+  not supplied: {input_name}` and the job fails immediately. This inconsistency between the
+  two dispatch types frequently surprises developers.
+
+  **GitHub API behavior (documented):** The REST API returns HTTP 204 (success) even when
+  required inputs are omitted. This is by design — GitHub treats `required: true` as a UI
+  hint only.
+fix: |
+  Treat `required: true` as UI-only and add explicit runtime validation at the top of your
+  workflow or job for any input that is truly required.
+
+  Use an `if:` guard or a validation step that fails the workflow immediately with a clear
+  error message when a required input is empty:
+
+  ```yaml
+  - name: Validate required inputs
+    run: |
+      if [ -z "${{ inputs.environment }}" ]; then
+        echo "::error::Input 'environment' is required but was not provided."
+        exit 1
+      fi
+  ```
+
+  For `gh workflow run` dispatch, newer versions of the CLI (v2.40+) will prompt for
+  required inputs interactively, but non-interactive (CI) invocations must pass `-f key=value`
+  explicitly.
+fix_code:
+  - language: yaml
+    label: "Validate required inputs at runtime with an early-exit step"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: "Target environment (required)"
+              required: true
+              type: choice
+              options: [staging, production]
+            version:
+              description: "Semantic version tag to deploy (required)"
+              required: true
+              type: string
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # Guard against API bypasses — required: true is UI-only
+            - name: Validate required inputs
+              run: |
+                MISSING=""
+                [ -z "${{ inputs.environment }}" ] && MISSING="$MISSING environment"
+                [ -z "${{ inputs.version }}" ]     && MISSING="$MISSING version"
+                if [ -n "$MISSING" ]; then
+                  echo "::error::Missing required inputs:$MISSING"
+                  exit 1
+                fi
+
+            - uses: actions/checkout@v4
+            - name: Deploy
+              run: ./deploy.sh "${{ inputs.environment }}" "${{ inputs.version }}"
+  - language: yaml
+    label: "Triggering with gh workflow run — always pass required inputs explicitly"
+    code: |
+      # ✅ Correct: pass all required inputs
+      gh workflow run deploy.yml \
+        -f environment=staging \
+        -f version=v1.2.3
+
+      # ❌ Wrong: omits required inputs — workflow still runs, inputs are empty strings
+      gh workflow run deploy.yml
+prevention:
+  - "Never rely on `required: true` alone for server-side enforcement — add a runtime validation step."
+  - "Document in your workflow that inputs must be passed explicitly when triggering via API or CI pipelines."
+  - "For security-critical workflows (deploy, release), use a job-level `if:` condition to block the entire job when an input is empty."
+  - "Consider reusable workflow (`workflow_call`) if you need server-enforced required inputs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Actions: workflow_dispatch event"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "REST API: Create a workflow dispatch event"
+  - url: "https://cli.github.com/manual/gh_workflow_run"
+    label: "gh workflow run — GitHub CLI manual"

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.10",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",