@htekdev/actions-debugger 1.0.9 → 1.0.11

package/errors/caching-artifacts/cache-cross-os-archive-missing.yml

@@ -0,0 +1,120 @@
+id: caching-artifacts-013
+title: "Cross-OS Cache Miss — enableCrossOsArchive Not Set"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cross-os
+  - windows
+  - linux
+  - cache-miss
+  - enableCrossOsArchive
+patterns:
+  - regex: "Cache not found for input keys"
+    flags: "i"
+  - regex: "enableCrossOsArchive.*false"
+    flags: "i"
+  - regex: "cache miss.*windows"
+    flags: "i"
+  - regex: "tar.*posix.*failed"
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys: <key>"
+  - "enableCrossOsArchive: false"
+  - "Cache saved successfully"
+  - "Post job cleanup."
+root_cause: |
+  `actions/cache` uses different archive formats depending on the runner OS:
+  - Linux/macOS: GNU tar (gnutar) with zstd compression
+  - Windows: BSD tar bundled with Git for Windows (`C:\Program Files\Git\usr\bin\tar.exe`)
+
+  When a cache is created on Linux or macOS, the archive is in GNU tar format. When
+  Windows attempts to restore it (or vice versa), the different tar implementation
+  fails to decompress the archive, resulting in a silent cache miss.
+
+  The `enableCrossOsArchive` option (default: `false`) controls whether the cache is
+  stored in a cross-platform-compatible format. Setting it to `true` forces GNU tar
+  format on all platforms, enabling cache sharing across OSes.
+
+  This is particularly common in monorepos where:
+  - Node modules or package caches are written by a Linux job and expected to be
+    restored by a Windows job in the same workflow run
+  - A "seed cache" job runs on Linux and downstream jobs run on Windows
+  - The matrix includes multiple OS values sharing the same cache key
+
+  Tracked in actions/cache#1275 (Cache miss on Windows despite a successful
+  cache-write) — confirmed fixed by setting `enableCrossOsArchive: true`.
+fix: |
+  Add `enableCrossOsArchive: true` to ALL cache steps (both the write and the restore
+  steps) that need to share caches across different OS runners.
+
+  IMPORTANT: The option must be set consistently on both the writing and reading jobs.
+  Setting it only on one side will not work.
+
+  If true cross-OS caching is not needed, ensure each OS creates its own native cache
+  by including `${{ runner.os }}` in the cache key.
+fix_code:
+  - language: yaml
+    label: "Enable cross-OS archive on cache steps that share between Linux and Windows"
+    code: |
+      - name: Cache node modules (cross-OS compatible)
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: node-${{ hashFiles('**/package-lock.json') }}
+          enableCrossOsArchive: true   # Required for Linux↔Windows cache sharing
+
+  - language: yaml
+    label: "OS-specific cache keys (alternative — each OS gets its own cache)"
+    code: |
+      - name: Cache dependencies (OS-scoped key — no cross-OS needed)
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          # Include runner.os so each OS writes its own cache entry
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+  - language: yaml
+    label: "Matrix workflow with consistent enableCrossOsArchive on all jobs"
+    code: |
+      jobs:
+        seed-cache:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Seed shared cache
+              uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: node-${{ hashFiles('**/package-lock.json') }}
+                enableCrossOsArchive: true
+
+        build:
+          needs: seed-cache
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Restore shared cache
+              uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: node-${{ hashFiles('**/package-lock.json') }}
+                enableCrossOsArchive: true   # Must match the write job
+
+prevention:
+  - "Always include `runner.os` in your cache key unless you explicitly need cross-OS sharing."
+  - "When cross-OS sharing IS required, set `enableCrossOsArchive: true` on every step that reads or writes the shared cache."
+  - "Treat cross-OS cache sharing as an explicit opt-in, not the default."
+  - "Test cache restoration on all target OSes during initial workflow setup."
+docs:
+  - url: "https://github.com/actions/cache/blob/main/README.md"
+    label: "actions/cache README: enableCrossOsArchive option"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache: Tips and workarounds (cross-OS section)"
+  - url: "https://github.com/actions/cache/issues/1275"
+    label: "actions/cache#1275: Cache miss on Windows despite a successful cache-write"

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/runner-environment/checkout-persist-credentials-false-git-auth.yml

@@ -0,0 +1,124 @@
+id: runner-environment-032
+title: "persist-credentials: false Breaks Subsequent Git Push / Authentication"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - persist-credentials
+  - git-push
+  - authentication
+  - credential-helper
+  - git-auto-commit
+patterns:
+  - regex: "fatal:.*could not read Username.*No such device"
+    flags: "i"
+  - regex: "fatal: Authentication failed for.*github\\.com"
+    flags: "i"
+  - regex: "remote:.*Invalid username or password"
+    flags: "i"
+  - regex: "persist-credentials.*false"
+    flags: "i"
+  - regex: "error: The requested URL returned error: 403"
+    flags: "i"
+error_messages:
+  - "fatal: could not read Username for 'https://github.com': No such device or address"
+  - "fatal: Authentication failed for 'https://github.com/owner/repo.git/'"
+  - "remote: Invalid username or password."
+  - "error: The requested URL returned error: 403"
+  - "remote: Support for password authentication was removed"
+root_cause: |
+  When `actions/checkout` runs with `persist-credentials: false`, it:
+  1. Checks out the repository
+  2. Explicitly **removes** the git credential helper that was configured for GITHUB_TOKEN auth
+  3. Leaves the working directory with no way to authenticate subsequent git operations
+
+  Any `git push`, `git pull`, or `git fetch` call that runs AFTER this checkout will
+  fail with an authentication error because there is no credential helper configured.
+
+  This pattern is often introduced deliberately for security (to avoid GITHUB_TOKEN
+  persistence), but developers forget that it also breaks any action or step that needs
+  to push changes back to the repository — such as:
+  - `stefanzweifel/git-auto-commit-action` (fails with "could not read Username")
+  - Manual `git push origin HEAD` steps
+  - Semantic-release, release-please, and other auto-committing tools
+  - Actions that amend, tag, or push version bumps
+
+  The issue is also triggered transitively: if a composite action internally calls
+  `actions/checkout` with `persist-credentials: false`, the credential helper is
+  removed from the runner's git config, breaking git auth for all subsequent steps.
+
+  Tracked across multiple issues: stefanzweifel/git-auto-commit-action#356,
+  stefanzweifel/git-auto-commit-action#397, anthropics/claude-code-action#1236.
+fix: |
+  **Option 1 (simplest): Remove persist-credentials: false**
+  If you set it out of habit or from a template, just remove it. GITHUB_TOKEN credentials
+  stored by actions/checkout are scoped to the runner and do not persist beyond the
+  workflow run anyway.
+
+  **Option 2: Re-configure credentials after checkout**
+  If you need `persist-credentials: false` for security reasons (e.g., to prevent
+  GITHUB_TOKEN from being used by untrusted code), re-add credentials only for the
+  steps that need to push.
+
+  **Option 3: Use SSH instead of HTTPS**
+  Configure SSH deploy keys and use an SSH remote URL to avoid HTTPS credential
+  issues entirely.
+fix_code:
+  - language: yaml
+    label: "Remove persist-credentials: false (simplest fix)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          # REMOVE this line — credentials are scoped to the runner by default
+          # persist-credentials: false
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "chore: auto-update generated files [skip ci]"
+          git push
+
+  - language: yaml
+    label: "Re-configure credentials after persist-credentials: false (security-first workflows)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false   # Untrusted code runs between here and push
+
+      # ... run untrusted/third-party code here ...
+
+      - name: Re-configure GITHUB_TOKEN for push
+        run: |
+          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+        # Now git push will work again
+
+      - name: Push changes
+        run: git push
+
+  - language: yaml
+    label: "Use PAT or app token to push (avoids GITHUB_TOKEN limitations)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.MY_PAT }}   # Use a PAT that has write access
+          persist-credentials: true     # Default: true — keep this to allow push
+
+      - name: Push changes
+        run: git push
+
+prevention:
+  - "Do not add `persist-credentials: false` unless you have a specific security reason (e.g., running untrusted fork code)."
+  - "If any step after `actions/checkout` needs to push commits or tags, ensure credentials are persisted or re-configured."
+  - "When using `git-auto-commit-action` or similar, check upstream docs for compatibility with `persist-credentials: false`."
+  - "Prefer `token: ${{ secrets.GITHUB_TOKEN }}` with `persist-credentials: true` over re-configuring remote URLs manually."
+docs:
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: persist-credentials input"
+  - url: "https://github.com/stefanzweifel/git-auto-commit-action/discussions/356"
+    label: "git-auto-commit-action#356: persist-credentials: false compatibility"
+  - url: "https://github.com/stefanzweifel/git-auto-commit-action/issues/397"
+    label: "git-auto-commit-action#397: fatal: could not read Username (checkout v5)"
+  - url: "https://github.com/anthropics/claude-code-action/issues/1236"
+    label: "claude-code-action#1236: fails when persist-credentials: false"

package/errors/silent-failures/checkout-fetch-depth-shallow-clone-breaks-history.yml

@@ -0,0 +1,104 @@
+id: silent-failures-013
+title: "Shallow Clone (fetch-depth: 1) Silently Breaks Git History Operations"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - fetch-depth
+  - shallow-clone
+  - git-describe
+  - changelog
+  - versioning
+patterns:
+  - regex: "fatal:.*No names found.*cannot describe anything"
+    flags: "i"
+  - regex: "fatal:.*no tag can describe"
+    flags: "i"
+  - regex: "git describe.*failed with exit code 128"
+    flags: "i"
+  - regex: "fetch-depth.*1"
+    flags: "i"
+error_messages:
+  - "fatal: No names found, cannot describe anything."
+  - "fatal: no tag can describe ''"
+  - "error: process completed with exit code 128"
+  - "git describe --tags --abbrev=0 failed"
+root_cause: |
+  `actions/checkout` defaults to `fetch-depth: 1`, which creates a shallow clone containing
+  only the most recent commit. This means:
+  - No commit history beyond the latest commit is available
+  - No tags are fetched (unless `fetch-tags: true` is set separately)
+  - Git operations that need history context fail silently or produce wrong results
+
+  Affected operations include:
+  - `git describe --tags` — fails with "No names found, cannot describe anything"
+  - `git log --oneline HEAD~10..HEAD` — returns nothing or errors
+  - Semantic versioning tools (semantic-release, standard-version, release-please)
+  - Changelog generators that diff HEAD against previous tags
+  - `git rev-list --count HEAD` — returns "1" instead of full commit count
+  - GitVersion, MinVer, and similar tag-based version calculators
+
+  The failure is silent in many cases: the step appears to succeed, but produces an
+  empty string, "0.0.0", or a fallback version instead of the expected semver.
+
+  Tracked in actions/checkout#217 (RFC: fetch-depth: 1 and not cloning tags are dangerous
+  defaults) with 22 thumbs-up reactions.
+fix: |
+  **Option 1 (recommended for most cases): Fetch full history**
+  Set `fetch-depth: 0` to fetch all commits and tags.
+
+  **Option 2: Fetch only enough history**
+  For large repos, fetch only the depth needed (e.g., last 50 commits). Use
+  `fetch-tags: true` (available in actions/checkout@v4) to fetch all tags without
+  the full commit history.
+
+  **Option 3: Unshallow after checkout**
+  Fetch the necessary history lazily with `git fetch --unshallow` or
+  `git fetch --tags --unshallow` as a subsequent step.
+fix_code:
+  - language: yaml
+    label: "Full history checkout (simplest fix)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # 0 = full history; default 1 = shallow
+
+      - name: Generate changelog
+        run: git log --oneline $(git describe --tags --abbrev=0 @^)..@ --no-merges
+
+  - language: yaml
+    label: "Fetch tags only without full history (faster for large repos)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # Required for tag-based versioning
+          fetch-tags: true   # Explicitly fetch all tags (actions/checkout v4.1.1+)
+
+  - language: yaml
+    label: "Unshallow lazily if full history is not needed upfront"
+    code: |
+      - uses: actions/checkout@v4
+        # fetch-depth: 1 (default — shallow clone)
+
+      - name: Fetch tags for versioning
+        run: |
+          git fetch --tags --force
+          # Or for full history:
+          # git fetch --unshallow
+
+      - name: Get version from tags
+        run: git describe --tags --abbrev=0
+
+prevention:
+  - "Add `fetch-depth: 0` to any checkout step that precedes git history, tag, or versioning operations."
+  - "Set `fetch-tags: true` in actions/checkout@v4 when using tag-based versioning tools."
+  - "When using semantic-release, release-please, or GitVersion, always use `fetch-depth: 0`."
+  - "Test locally with `git clone --depth 1` to reproduce the shallow clone environment before debugging in CI."
+  - "Audit all checkout steps in release workflows — shallow clones are fine for build/test but break release automation."
+docs:
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: fetch-depth and fetch-tags inputs"
+  - url: "https://github.com/actions/checkout/issues/217"
+    label: "actions/checkout#217: RFC — fetch-depth: 1 and not cloning tags are dangerous defaults"
+  - url: "https://stackoverflow.com/questions/66349002/get-latest-tag-git-describe-tags-when-repo-is-cloned-with-depth-1"
+    label: "Stack Overflow: git describe fails when cloned with depth=1"

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-filters-silently-ignored.yml

@@ -0,0 +1,131 @@
+id: triggers-011
+title: "workflow_dispatch branches/paths Filters Silently Ignored or Cause Validation Error"
+category: triggers
+severity: warning
+tags:
+  - workflow_dispatch
+  - branches
+  - paths
+  - filters
+  - trigger
+  - manual-dispatch
+patterns:
+  - regex: "Unexpected value 'branches'"
+    flags: "i"
+  - regex: "workflow_dispatch.*branches.*paths"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unexpected value"
+    flags: "i"
+  - regex: "on\\.workflow_dispatch.*branches"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/deploy.yml (Line: X, Col: Y): Unexpected value 'branches'"
+  - "Unexpected value 'branches'"
+  - "Unexpected value 'tags'"
+  - "Unexpected value 'paths'"
+root_cause: |
+  `workflow_dispatch` is a manual trigger — it runs when a user (or the API) explicitly
+  triggers the workflow. Because it is not event-driven by a push or pull request, the
+  `branches`, `paths`, `tags`, and `paths-ignore` filters that apply to push/pull_request
+  events are **not valid** for `workflow_dispatch`.
+
+  Two failure modes exist:
+
+  **Mode 1: Validation error (branches, tags)**
+  Adding `branches` or `tags` under `on.workflow_dispatch` now produces a schema
+  validation error: "Unexpected value 'branches'" or "Unexpected value 'tags'".
+  GitHub used to silently ignore these keys (pre-2022), leading to copy-paste templates
+  with these keys still floating around. The workflow may fail to queue at all.
+
+  **Mode 2: Silent ignore (paths)**
+  The `paths` filter under `on.workflow_dispatch` was silently ignored historically.
+  The workflow runs regardless of which files changed (or didn't change), because
+  workflow_dispatch has no file-change context to filter on.
+
+  Developers commonly copy a push-triggered workflow and add workflow_dispatch without
+  removing the push-specific filters, producing this mistake:
+
+  ```yaml
+  on:
+    push:
+      branches: [main]
+      paths: ['src/**']
+    workflow_dispatch:
+      branches: [main]   # ← INVALID for workflow_dispatch
+      paths: ['src/**']  # ← silently ignored for workflow_dispatch
+  ```
+
+  Tracked in github/docs#34884 ("documentation on workflow_dispatch is not
+  correct/complete") and blog post by Jon Gallant (2022): "workflow_dispatch never
+  supported branches, but GH silently ignored it."
+fix: |
+  Remove `branches`, `paths`, `tags`, and `paths-ignore` from the `workflow_dispatch`
+  block entirely. These filters only apply to `push`, `pull_request`, and
+  `pull_request_target` triggers.
+
+  If you want manual dispatch to only be available on specific branches, use the
+  GitHub Actions UI branch selector at runtime — it allows choosing which branch to
+  run the workflow on during manual dispatch without needing a filter in the YAML.
+
+  If you need path-based conditional logic in a manually-triggered workflow, use
+  `dorny/paths-filter` or a custom `git diff` step to check which files changed after
+  the workflow starts.
+fix_code:
+  - language: yaml
+    label: "Remove invalid filters from workflow_dispatch block"
+    code: |
+      on:
+        push:
+          branches: [main]
+          paths: ['src/**']   # ← valid here for push
+        workflow_dispatch:
+          # ← Do NOT add branches/paths/tags here — they are not supported
+          # Use inputs if you need runtime parameterization:
+          inputs:
+            environment:
+              description: "Target environment"
+              required: true
+              default: "staging"
+              type: choice
+              options: [staging, production]
+
+  - language: yaml
+    label: "Path-based conditional logic inside a manually-dispatched workflow"
+    code: |
+      on:
+        workflow_dispatch:
+
+      jobs:
+        check-and-deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2
+
+            - name: Check changed paths
+              id: filter
+              uses: dorny/paths-filter@v3
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+
+            - name: Deploy (only if src changed)
+              if: steps.filter.outputs.src == 'true'
+              run: echo "Deploying..."
+
+prevention:
+  - "Never copy `branches`, `paths`, or `tags` filters from a `push` block into a `workflow_dispatch` block."
+  - "Treat `workflow_dispatch` as a parameter-based trigger, not a filter-based one — use `inputs` instead."
+  - "If the GitHub Actions linter flags 'Unexpected value branches', remove it from the workflow_dispatch block."
+  - "Use the branch selector in the GitHub Actions UI for branch scoping at runtime."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs: workflow_dispatch event trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore"
+    label: "GitHub Docs: paths filter (push/pull_request only)"
+  - url: "https://github.com/github/docs/issues/34884"
+    label: "github/docs#34884: documentation on workflow_dispatch is not correct/complete"
+  - url: "https://blog.jongallant.com/2022/04/github-actions-failing-with-unexpected-value-branches"
+    label: "Jon Gallant: workflow_dispatch never supported branches (2022)"

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/matrix-include-extra-standalone-jobs.yml

@@ -0,0 +1,136 @@
+id: yaml-syntax-017
+title: "Matrix include Entry Without Matching Combination Creates Unexpected Standalone Jobs"
+category: yaml-syntax
+severity: warning
+tags:
+  - matrix
+  - include
+  - strategy
+  - extra-jobs
+  - standalone
+  - job-count
+patterns:
+  - regex: "strategy.*matrix.*include"
+    flags: "i"
+  - regex: "matrix.*include.*extra.*job"
+    flags: "i"
+  - regex: "include.*os.*version"
+    flags: "i"
+error_messages:
+  - "strategy.matrix.include"
+  - "unexpected job combination in matrix"
+root_cause: |
+  GitHub Actions matrix `include` entries serve two purposes:
+  1. **Add variables to existing combinations** — when the entry shares at least one
+     key-value pair with an existing matrix combination, it adds/overrides variables
+     for that specific combination only.
+  2. **Create new standalone jobs** — when the entry does NOT match any existing matrix
+     combination, GitHub Actions treats it as an entirely NEW matrix job on its own.
+
+  This second behavior surprises developers who expect `include` to only add metadata
+  to existing jobs. Example that creates an unexpected extra job:
+
+  ```yaml
+  strategy:
+    matrix:
+      os: [ubuntu-latest, windows-latest]
+      node: [18, 20]
+      include:
+        - os: macos-latest      # ← No matching {os: macos-latest} in matrix
+          node: 20
+          experimental: true   # ← This creates a BRAND NEW 5th job, not expected
+  ```
+
+  The matrix produces: 4 jobs from combinations (ubuntu×18, ubuntu×20,
+  windows×18, windows×20) PLUS an extra 5th job for (macos-latest × 20 × experimental).
+
+  This can also cause subtle bugs when a typo in an `include` value fails to match
+  the existing combination, silently creating an extra duplicate-like job:
+
+  ```yaml
+  include:
+    - os: ubuntu-latest   # os key matches!
+      node: 18
+      runs-long: true     # Variable added to ubuntu-latest×18 job ✓
+    - os: ubuntu          # TYPO: doesn't match "ubuntu-latest" → new standalone job ✗
+      node: 18
+      experimental: true
+  ```
+
+  Tracked in github/docs#23322 ("Documentation for jobs matrix strategy seems incorrect").
+fix: |
+  **To add variables to existing combinations:** Ensure at least one key in the
+  `include` entry exactly matches an existing combination value. The match is
+  case-sensitive.
+
+  **To intentionally add a new job:** This is valid behavior — just document it clearly
+  in the workflow and be aware of the extra job in your branch protection rules.
+
+  **To prevent accidental extra jobs:** Review the job count after adding include entries.
+  The total should be: (product of all matrix dimensions) + (number of include entries
+  that don't match any combination).
+fix_code:
+  - language: yaml
+    label: "include entry that correctly adds a variable to an existing combination"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest]
+          node: [18, 20]
+          include:
+            # This MATCHES ubuntu-latest×18 — adds 'experimental: true' to that job only
+            - os: ubuntu-latest  # ← must exactly match the matrix value
+              node: 18           # ← must exactly match the matrix value
+              experimental: true
+
+            # This MATCHES all ubuntu-latest jobs (node 18 AND 20)
+            # because os key matches and node is not specified
+            - os: ubuntu-latest
+              runs-slow: true    # added to ubuntu-latest×18 AND ubuntu-latest×20
+
+  - language: yaml
+    label: "Intentional standalone job via include (extra OS not in base matrix)"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest]
+          node: [18, 20]
+          include:
+            # Intentional extra job — macos is not in the base matrix
+            # Documents clearly that this creates job #5 (macos×20)
+            - os: macos-latest
+              node: 20
+              experimental: true
+      # Total jobs: 4 (base combinations) + 1 (macos standalone) = 5
+
+  - language: yaml
+    label: "Verify total job count matches expectations with exclude"
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest, macos-latest]
+          node: [18, 20]
+          exclude:
+            # Exclude expensive macos×18 — not needed
+            - os: macos-latest
+              node: 18
+          include:
+            # Add experimental flag to ubuntu-latest×20 only
+            - os: ubuntu-latest
+              node: 20
+              experimental: true
+      # Total jobs: (3×2) - 1 excluded = 5 jobs; 0 new from include (it matches existing)
+
+prevention:
+  - "Always verify the total expected job count after adding `include` entries."
+  - "Ensure `include` key-value pairs exactly match (case-sensitive) the base matrix values."
+  - "Use a comment in the workflow to document the expected total number of jobs."
+  - "If a typo causes an unexpected extra job, it will show up as a job with no matching `if:` context — watch for jobs that run but shouldn't."
+  - "Use `exclude` to remove specific combinations instead of relying solely on `include` overrides."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#expanding-or-adding-matrix-configurations"
+    label: "GitHub Docs: Expanding or adding matrix configurations with include"
+  - url: "https://github.com/github/docs/issues/23322"
+    label: "github/docs#23322: Documentation for jobs matrix strategy seems incorrect"
+  - url: "https://stackoverflow.com/questions/78821409/github-actions-matrix-job-running-despite-false-conditions"
+    label: "Stack Overflow: GitHub Actions matrix job running despite false conditions"

package/package.json

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