@htekdev/actions-debugger 1.0.41 → 1.0.43

package/errors/caching-artifacts/upload-artifact-v4-duplicate-name-hard-error.yml

@@ -0,0 +1,114 @@
+id: caching-artifacts-033
+title: 'upload-artifact@v4 requires unique artifact names per run — duplicate name is a hard error'
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - v4
+  - duplicate-name
+  - breaking-change
+  - matrix
+patterns:
+  - regex: 'An artifact with this name already exists on the workflow run'
+    flags: 'i'
+  - regex: 'Failed to CreateArtifact.*already exists'
+    flags: 'i'
+error_messages:
+  - 'An artifact with this name already exists on the workflow run'
+  - 'Failed to CreateArtifact: Artifact already exists'
+root_cause: |
+  actions/upload-artifact@v4 changed artifact name uniqueness enforcement from v3:
+
+  v3 behavior: uploading with a duplicate name silently merged the new files
+  into the existing artifact, potentially overwriting same-named files.
+
+  v4 behavior: uploading with a name that already exists in the same workflow
+  run is a hard error. The step fails immediately with:
+    "An artifact with this name already exists on the workflow run"
+
+  Common triggers:
+  1. Matrix jobs all writing to a fixed artifact name (e.g., name: build-output)
+     without including a matrix dimension in the name.
+  2. Multiple upload-artifact steps in the same job with the same name: value.
+  3. Reusable workflows invoked multiple times in one run using identical names.
+  4. Two upload steps with no name: parameter — both default to "artifact".
+
+  Workflows that relied on v3's merge behavior and were silently uploading
+  duplicate names will fail immediately after upgrading to v4.
+fix: |
+  Include a unique identifier in the artifact name for each upload step.
+  For matrix jobs, include a matrix dimension value. For independent parallel
+  jobs, include the job name or a specific run-scoped identifier.
+
+  If you need to consolidate artifacts from multiple sources, have each job
+  upload with a unique name, then use a final consolidation job that downloads
+  all artifacts and re-uploads a merged set.
+fix_code:
+  - language: yaml
+    label: 'Matrix jobs — include matrix dimension in artifact name'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest, macos-latest]
+
+      steps:
+        - name: Build
+          run: make build
+
+        - uses: actions/upload-artifact@v4
+          with:
+            name: build-output-${{ matrix.os }}   # Unique per matrix cell
+            path: dist/
+  - language: yaml
+    label: 'Multiple upload steps — use distinct explicit names'
+    code: |
+      steps:
+        - uses: actions/upload-artifact@v4
+          with:
+            name: test-results       # Distinct name
+            path: test-output/
+
+        - uses: actions/upload-artifact@v4
+          with:
+            name: coverage-report    # Different name — no conflict
+            path: coverage/
+  - language: yaml
+    label: 'Merge artifacts across matrix jobs in a downstream job'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+          steps:
+            - uses: actions/upload-artifact@v4
+              with:
+                name: dist-${{ matrix.os }}
+                path: dist/
+
+        package:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: dist-*
+                merge-multiple: true
+                path: all-dist/
+
+            - uses: actions/upload-artifact@v4
+              with:
+                name: final-package
+                path: all-dist/
+prevention:
+  - 'Always specify an explicit name: for each upload-artifact step rather than relying on the default "artifact"'
+  - 'For matrix jobs, include at least one matrix variable in the artifact name'
+  - 'Audit workflows being migrated from v3 to v4 for any step that omits name: or uses the same name twice'
+  - 'Two steps with no name: both default to "artifact" and will always conflict in v4'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/blob/main/docs/MIGRATION.md'
+    label: 'upload-artifact v3 to v4 migration guide'
+  - url: 'https://github.com/actions/upload-artifact'
+    label: 'actions/upload-artifact repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts'
+    label: 'GitHub Docs — Storing workflow data as artifacts'

package/errors/permissions-auth/job-level-permissions-replaces-workflow-level.yml

@@ -0,0 +1,123 @@
+id: permissions-auth-034
+title: 'Job-level permissions: block replaces workflow-level permissions — undeclared scopes are silently removed'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - permissions
+  - GITHUB_TOKEN
+  - job-level
+  - workflow-level
+  - 403
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'HttpError.*403'
+    flags: 'i'
+error_messages:
+  - 'Resource not accessible by integration'
+  - 'HttpError: Resource not accessible by integration'
+  - '403 Forbidden'
+root_cause: |
+  The permissions: block in GitHub Actions is a REPLACEMENT at the scope where
+  it is applied — it does NOT inherit or merge with permissions defined at a
+  parent scope.
+
+  Example: if a workflow defines top-level permissions:
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+  And a job within that workflow also defines permissions:
+    permissions:
+      deployments: write
+
+  Then that job's GITHUB_TOKEN has ONLY deployments: write. The
+  contents: write, issues: write, and pull-requests: write scopes are
+  completely dropped for that job.
+
+  Developers expect job-level permissions to be ADDITIVE (adding new
+  permissions on top of the workflow-level set). The actual behavior is the
+  opposite: job-level permissions creates an entirely new permission set for
+  that job, discarding all workflow-level grants not re-declared.
+
+  The failure is silent — no warning is emitted about the permission reduction.
+  Steps produce 403 or "Resource not accessible by integration" only when
+  they actually attempt to use the silently-removed permission.
+fix: |
+  When using a job-level permissions: block, re-declare ALL permissions
+  that the job needs — not just the new ones you want to add.
+
+  Alternatively, if all jobs in the workflow need the same permission set,
+  set permissions only at the workflow level and omit job-level overrides.
+
+  Best practice: prefer job-level permissions over workflow-level for the
+  principle of least privilege — each job explicitly declares only what it
+  needs, with no inheritance confusion.
+fix_code:
+  - language: yaml
+    label: 'Wrong: job-level block silently drops workflow-level grants'
+    code: |
+      # Workflow level
+      permissions:
+        contents: write
+        issues: write
+
+      jobs:
+        deploy:
+          permissions:
+            deployments: write   # This REPLACES the above — contents and issues are now GONE
+          steps:
+            - name: Comment on issue
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  # This will 403 — issues: write was silently removed
+                  await github.rest.issues.createComment({ issue_number: 1, body: 'deployed' })
+  - language: yaml
+    label: 'Correct: re-declare all needed permissions at job level'
+    code: |
+      # No workflow-level permissions block needed when using job-level
+
+      jobs:
+        deploy:
+          permissions:
+            contents: write      # Re-declared (was at workflow level)
+            issues: write        # Re-declared (was at workflow level)
+            deployments: write   # New permission added
+          steps:
+            - name: Comment on issue
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.issues.createComment({ issue_number: 1, body: 'deployed' })
+  - language: yaml
+    label: 'Minimal job permissions — each job declares only what it needs'
+    code: |
+      # No workflow-level permissions block — all scoped to jobs
+
+      jobs:
+        test:
+          permissions:
+            checks: write
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+        deploy:
+          permissions:
+            contents: read
+            deployments: write
+            id-token: write
+          steps:
+            - run: echo "deploying"
+prevention:
+  - 'When adding a job-level permissions block, start by listing every permission the job needs from scratch'
+  - 'Do not assume any permissions flow down from the workflow level when a job block is present'
+  - 'Prefer defining all permissions at the job level (not workflow level) to make the permission set explicit'
+  - 'The GitHub Docs explicitly state: permissions at the job level override the workflow-level setting'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'GitHub Docs — Controlling permissions for GITHUB_TOKEN'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions'
+    label: 'GitHub Docs — jobs.<job_id>.permissions syntax'

package/errors/runner-environment/runner-workspace-vs-github-workspace-parent-directory.yml

@@ -0,0 +1,100 @@
+id: runner-environment-098
+title: "runner.workspace is the parent of the repo root — not the checked-out repo"
+category: runner-environment
+severity: silent-failure
+tags:
+  - runner.workspace
+  - github.workspace
+  - path
+  - working-directory
+  - context
+patterns:
+  - regex: 'runner\.workspace'
+    flags: i
+  - regex: '\$\{\{\s*runner\.workspace\s*\}\}'
+    flags: i
+error_messages:
+  - "No such file or directory"
+  - "Error: Path does not exist"
+  - "ENOENT: no such file or directory"
+root_cause: |
+  Two similarly-named contexts point to DIFFERENT directories on GitHub-hosted
+  runners:
+
+    github.workspace  = /home/runner/work/REPO/REPO   ← the checked-out repo root
+    runner.workspace  = /home/runner/work/REPO        ← one level ABOVE the repo root
+
+  runner.workspace is the "runner work directory" that CONTAINS the repo clone
+  folder, not the repo itself. The official documentation describes this distinction,
+  but the names are confusingly similar and many developers assume runner.workspace
+  is equivalent to "where my code is" — which is github.workspace.
+
+  Consequences:
+  - working-directory: ${{ runner.workspace }} silently points one level above
+    the repo, causing file-not-found errors on relative paths inside the repo.
+  - Path-building expressions like runner.workspace + '/src' resolve to a
+    path that doesn't exist.
+  - The error surfaces as "No such file or directory" or a missing file, not as
+    a context resolution failure, making the root cause hard to identify.
+
+  On some self-hosted runner configurations both paths may resolve to the same
+  directory, masking the bug until the workflow runs on a GitHub-hosted runner.
+
+  Source: GitHub Actions contexts documentation; GitHub Community/15327;
+  Stack Overflow path confusion questions with 100K+ combined views.
+fix: |
+  Replace runner.workspace with github.workspace (or the $GITHUB_WORKSPACE
+  environment variable) when the intent is to reference the checked-out repo root.
+
+  Use runner.workspace only when intentionally targeting the parent directory
+  that contains the repo clone — for example, creating a sibling directory for
+  build artifacts that should live outside the repo tree.
+fix_code:
+  - language: yaml
+    label: "Use github.workspace for the repo root"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ WRONG — runner.workspace is one level ABOVE the repo
+            # - name: Wrong path
+            #   working-directory: ${{ runner.workspace }}
+
+            # ✅ CORRECT — github.workspace is the repo root
+            - name: List repo files
+              run: ls ${{ github.workspace }}
+
+            # ✅ ALSO CORRECT — $GITHUB_WORKSPACE env var is identical
+            - name: Build from repo root
+              working-directory: ${{ github.workspace }}
+              run: ls .
+
+            # ✅ Intentional use of runner.workspace — sibling dir outside repo
+            - name: Create output dir alongside repo
+              run: mkdir ${{ runner.workspace }}/build-output
+  - language: yaml
+    label: "Directory layout reference"
+    code: |
+      # GitHub-hosted runner path layout:
+      #
+      # /home/runner/work/
+      # └── my-repo/                 ← runner.workspace  (${{ runner.workspace }})
+      #     └── my-repo/             ← github.workspace  (${{ github.workspace }})
+      #         ├── src/
+      #         ├── package.json
+      #         └── .github/
+      #
+      # $GITHUB_WORKSPACE == ${{ github.workspace }} (same value, two access methods)
+prevention:
+  - "Always use github.workspace (or $GITHUB_WORKSPACE) to reference the checked-out repo root"
+  - "Reserve runner.workspace for intentional parent-directory operations such as sibling build directories"
+  - "When debugging path issues, print both: echo $GITHUB_WORKSPACE and echo ${{ runner.workspace }}"
+  - "Self-hosted runner paths may differ from GitHub-hosted runners — use named contexts rather than hardcoded absolute paths"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Actions — github context (workspace)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#runner-context"
+    label: "GitHub Actions — runner context (workspace)"

package/errors/silent-failures/actions-runner-debug-wrong-secret-name.yml

@@ -0,0 +1,90 @@
+id: silent-failures-045
+title: "ACTIONS_RUNNER_DEBUG / ACTIONS_STEP_DEBUG typo — debug logging silently disabled"
+category: silent-failures
+severity: silent-failure
+tags:
+  - debug
+  - ACTIONS_RUNNER_DEBUG
+  - ACTIONS_STEP_DEBUG
+  - secrets
+  - diagnostic
+patterns:
+  - regex: 'RUNNER_DEBUG'
+    flags: ''
+  - regex: 'ACTIONS_DEBUG'
+    flags: i
+error_messages: []
+root_cause: |
+  GitHub Actions debug logging is controlled by two specific repository secrets
+  (or repository variables since October 2023):
+
+    ACTIONS_RUNNER_DEBUG = "true"  — runner diagnostic logs (runner.diag.log,
+      Worker_*.log files attached to the run as a downloadable zip)
+    ACTIONS_STEP_DEBUG = "true"    — verbose step-level debug output shown
+      inline in each step log section
+
+  When developers set secrets with incorrect names such as RUNNER_DEBUG, DEBUG,
+  ACTIONS_DEBUG, or ENABLE_DEBUG, GitHub silently ignores them. The workflow
+  runs normally with no indication that debug logging was never activated.
+  The developer sees only standard log output and assumes there is nothing more
+  to inspect.
+
+  A secondary failure mode: setting these as workflow-level env: variables has
+  no effect — debug logging requires them as repository secrets or repository
+  variables, not env: entries.
+
+  Source: GitHub Docs — Enabling debug logging; GitHub Community recurring
+  reports of debug logs not appearing despite secrets being set.
+fix: |
+  Set repository secrets or repository variables with the EXACT names:
+    ACTIONS_RUNNER_DEBUG  (value: true)
+    ACTIONS_STEP_DEBUG    (value: true)
+
+  Path: Repository Settings → Secrets and variables → Actions → New repository secret.
+
+  These can also be set at the organization level to apply across all repos.
+
+  Runner diagnostic logs from ACTIONS_RUNNER_DEBUG are available as a
+  downloadable zip file attached to the workflow run — not shown inline.
+  Step debug logs from ACTIONS_STEP_DEBUG appear inline in each step as
+  collapsed "##[debug]" lines.
+fix_code:
+  - language: yaml
+    label: "workflow_dispatch input to enable debug for a single run without changing secrets"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            debug_enabled:
+              type: boolean
+              description: 'Enable step debug logging for this run'
+              default: false
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Enable step debug mode
+              if: ${{ inputs.debug_enabled }}
+              run: echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV
+
+            - name: Build step (verbose when debug enabled)
+              run: echo "Build running"
+  - language: yaml
+    label: "Check which debug secrets are active"
+    code: |
+      - name: Show debug context
+        run: |
+          echo "Runner debug: $ACTIONS_RUNNER_DEBUG"
+          echo "Step debug:   $ACTIONS_STEP_DEBUG"
+          # If these print empty string, the secrets are not set or named incorrectly
+prevention:
+  - "Use exactly 'ACTIONS_RUNNER_DEBUG' and 'ACTIONS_STEP_DEBUG' as the secret names — no other names work"
+  - "Set these as repository secrets or repository variables, not as env: in workflow YAML"
+  - "ACTIONS_RUNNER_DEBUG logs are in a separate zip download — check the run's uploaded artifacts section"
+  - "Both secrets can be enabled simultaneously; they control independent output streams"
+docs:
+  - url: "https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging"
+    label: "GitHub Docs — Enabling debug logging"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs — Storing information in variables"

package/errors/silent-failures/composite-action-outputs-not-propagated.yml

@@ -0,0 +1,99 @@
+id: silent-failures-048
+title: 'Composite action outputs not propagated — outputs: declaration required in action.yml'
+category: silent-failures
+severity: silent-failure
+tags:
+  - composite
+  - outputs
+  - action.yml
+  - step-outputs
+  - empty-string
+patterns:
+  - regex: 'steps\.\w+\.outputs\.'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  In composite actions, step outputs from internal steps are NOT automatically
+  visible to the action's callers. The composite action's action.yml must
+  declare an outputs: block that explicitly maps each output name to a value
+  expression referencing an internal step's output:
+
+    outputs:
+      my-result:
+        description: "The result"
+        value: ${{ steps.build.outputs.result }}
+
+  Without this declaration, ${{ steps.my-action.outputs.my-result }} in the
+  calling workflow evaluates to empty string with no error or warning.
+
+  This is different from regular workflow jobs, where step outputs are
+  accessible within the same job via steps.<id>.outputs.<name> without any
+  explicit mapping. Composite actions require explicit wiring because the
+  action boundary creates an isolation layer — internal step IDs are not
+  exposed to callers.
+
+  Common mistake pattern: developer tests the composite action, sees that
+  internal steps set outputs correctly, but the caller always receives "".
+  The action.yml outputs: block is missing or references a wrong step id.
+fix: |
+  1. Open the composite action's action.yml file.
+  2. Add an outputs: block (after the inputs: block if present).
+  3. For each output you need to expose, add an entry with:
+       value: ${{ steps.<internal-step-id>.outputs.<output-name> }}
+  4. Ensure the referenced internal step has a matching id: field.
+  5. Ensure the internal step writes outputs via GITHUB_OUTPUT:
+       echo "result=value" >> $GITHUB_OUTPUT
+fix_code:
+  - language: yaml
+    label: 'action.yml — declare outputs with value expressions'
+    code: |
+      # .github/actions/my-build/action.yml
+      name: 'My Build Action'
+      description: 'Builds the project and returns the version'
+
+      outputs:
+        build-version:
+          description: 'The version that was built'
+          value: ${{ steps.get-version.outputs.version }}
+        artifact-path:
+          description: 'Path to the built artifact'
+          value: ${{ steps.build.outputs.artifact }}
+
+      runs:
+        using: composite
+        steps:
+          - id: get-version
+            shell: bash
+            run: echo "version=$(cat version.txt)" >> $GITHUB_OUTPUT
+
+          - id: build
+            shell: bash
+            run: |
+              make build
+              echo "artifact=dist/app.tar.gz" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: 'Calling workflow — accessing composite action outputs'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - id: build
+              uses: ./.github/actions/my-build
+
+            - name: Use outputs
+              run: |
+                echo "Version: ${{ steps.build.outputs.build-version }}"
+                echo "Artifact: ${{ steps.build.outputs.artifact-path }}"
+prevention:
+  - 'Every composite action output must have a corresponding entry in the outputs: block of action.yml'
+  - 'Internal steps must have an id: field for the outputs value: expression to reference'
+  - 'The step id in the value: expression must exactly match the internal step id: value'
+  - 'Add a debug step in the action to print $GITHUB_OUTPUT contents when troubleshooting'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions'
+    label: 'GitHub Docs — Outputs for composite actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Docs — Passing information between jobs'

package/errors/silent-failures/github-env-vars-not-shared-across-jobs.yml

@@ -0,0 +1,96 @@
+id: silent-failures-047
+title: "GITHUB_ENV variables are job-scoped — not shared with downstream needs: jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_ENV
+  - environment-variables
+  - job-outputs
+  - cross-job
+  - silent-failure
+patterns:
+  - regex: 'GITHUB_ENV'
+    flags: ''
+  - regex: 'echo\s+".+=.+"\s*>>\s*\$GITHUB_ENV'
+    flags: i
+error_messages: []
+root_cause: |
+  Environment variables written to $GITHUB_ENV are scoped to the CURRENT JOB
+  only. They persist across all subsequent steps within that job, but are NOT
+  propagated to any other job — including jobs that depend on the producing
+  job via needs:.
+
+  This is a silent failure because:
+  1. The producing step exits 0 with no warning
+  2. The downstream job runs normally with no error message
+  3. The variable evaluates to empty string in the downstream job
+  4. Steps that depend on the value produce wrong results or silently skip
+     based on the empty string condition
+
+  Common scenario (silently broken):
+    Job A: echo "VERSION=1.2.3" >> $GITHUB_ENV
+    Job B (needs: job-a): echo $VERSION  → prints empty string
+
+  The correct mechanism for sharing values across job boundaries is job outputs
+  combined with the needs context. GITHUB_ENV is appropriate only for values
+  that need to persist across multiple steps within the same job.
+
+  Source: GitHub Docs — Passing information between jobs; GitHub Community and
+  Stack Overflow cross-job environment variable questions.
+fix: |
+  To pass a value from one job to a downstream job:
+
+  1. Write the value to $GITHUB_OUTPUT (not $GITHUB_ENV) in the producing step
+  2. Declare the step output in the producing job's outputs: block
+  3. Reference the value in the consuming job via ${{ needs.job-id.outputs.key }}
+
+  Continue using $GITHUB_ENV when the value only needs to be available to later
+  steps within the same job.
+fix_code:
+  - language: yaml
+    label: "Correct cross-job value sharing via GITHUB_OUTPUT and job outputs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            # Expose the step output as a job output
+            version: ${{ steps.get-version.outputs.version }}
+          steps:
+            - id: get-version
+              # Write to GITHUB_OUTPUT for cross-job sharing, not GITHUB_ENV
+              run: echo "version=1.2.3" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use version from build job
+              run: echo "Deploying version ${{ needs.build.outputs.version }}"
+  - language: yaml
+    label: "GITHUB_ENV is correct for within-job cross-step sharing"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Set version for this job's steps
+              run: echo "VERSION=1.2.3" >> $GITHUB_ENV
+
+            - name: Step 2 in same job — $VERSION is available
+              run: echo "Building $VERSION"
+
+            - name: Step 3 in same job — $VERSION is still available
+              run: echo "Packaging $VERSION"
+
+            # $VERSION is NOT available in any other job
+prevention:
+  - "Use GITHUB_OUTPUT + job outputs: for any value that must cross a job boundary"
+  - "Use GITHUB_ENV only for values shared between steps within the same job"
+  - "Add a verification step in the consuming job that echoes the value and fails if empty"
+  - "Avoid setting both GITHUB_ENV and GITHUB_OUTPUT for the same value — use GITHUB_OUTPUT as the single source of truth"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs — Passing information between jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs — Storing information in variables (GITHUB_ENV)"

package/errors/silent-failures/matrix-exclude-value-mismatch-silently-ignored.yml

@@ -0,0 +1,96 @@
+id: silent-failures-046
+title: "matrix.exclude silently ignored when value doesn't exactly match matrix dimension"
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - exclude
+  - strategy
+  - configuration
+  - silent-failure
+patterns:
+  - regex: 'exclude:'
+    flags: ''
+  - regex: 'strategy:\s*\n\s*matrix:'
+    flags: im
+error_messages: []
+root_cause: |
+  GitHub Actions matrix exclude: uses exact string equality. An exclude entry
+  removes a combination only when ALL specified key-value pairs exactly match
+  a generated matrix combination. If any pair fails to match, the combination
+  is silently kept.
+
+  Three common silent-failure patterns:
+
+  1. Value substring mismatch:
+       matrix: {os: [ubuntu-latest, windows-latest]}
+       exclude: [{os: ubuntu}]          # 'ubuntu' != 'ubuntu-latest' → ignored
+
+  2. Key not present in matrix dimensions:
+       matrix: {os: [ubuntu-latest], node: [18, 20]}
+       exclude: [{os: ubuntu-latest, version: 18}]   # 'version' not a matrix key → ignored
+
+  3. Type mismatch in some expression contexts:
+       matrix: {node: [18, 20]}
+       exclude: [{node: "18"}]           # string "18" may not equal integer 18
+
+  GitHub produces no warning when an exclude entry matches zero combinations.
+  The unwanted job continues to run, consuming CI minutes with no indication
+  that the exclude rule was ineffective.
+
+  Source: GitHub Docs matrix strategy; GitHub Community/26957; Stack Overflow
+  questions about matrix exclude not working as expected.
+fix: |
+  Use the exact string that appears in your matrix definition when writing
+  exclude entries. Run a matrix debug step to confirm the actual values
+  GitHub generates before relying on exclusions.
+
+  For complex exclusion logic involving substring matching or multiple
+  conditions, use the if: condition on the job instead of exclude:.
+  The if: condition can use contains(), startsWith(), and other expression
+  functions that exact-match exclude cannot.
+fix_code:
+  - language: yaml
+    label: "Correct exclude — exact value match required"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: [18, 20, 22]
+              exclude:
+                # Value must match EXACTLY what appears in the matrix list above
+                - os: windows-latest    # ✅ exact match
+                  node: 18
+                # Incorrect examples (silently ignored):
+                # - os: windows         # ❌ 'windows' != 'windows-latest'
+                # - os: windows-latest
+                #   version: 18         # ❌ 'version' not a matrix dimension key
+          runs-on: ${{ matrix.os }}
+          steps:
+            - name: Debug matrix combination
+              run: echo '${{ toJSON(matrix) }}'
+  - language: yaml
+    label: "Alternative — use if: for flexible exclusion"
+    code: |
+      jobs:
+        test:
+          # Use if: when you need startsWith / contains logic
+          if: >-
+            !(matrix.os == 'windows-latest' && matrix.node == 18)
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+              node: [18, 20]
+          runs-on: ${{ matrix.os }}
+prevention:
+  - "Use the exact strings from your matrix definition in exclude entries — copy-paste, do not retype"
+  - "Add a debug step printing toJSON(matrix) to verify which combinations GitHub actually generates"
+  - "Use if: conditions for substring matching, contains(), or multi-condition exclusion logic"
+  - "Test matrix changes on a branch and review the job list before merging to confirm excluded combinations are gone"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#excluding-matrix-configurations"
+    label: "GitHub Docs — Excluding matrix configurations"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "GitHub Docs — Using conditions to control job execution"

package/errors/triggers/workflow-run-name-mismatch-silent-never-triggers.yml

@@ -0,0 +1,96 @@
+id: triggers-032
+title: 'on.workflow_run.workflows matches name: field not filename — mismatch silently never triggers'
+category: triggers
+severity: warning
+tags:
+  - workflow_run
+  - trigger
+  - name-mismatch
+  - silent
+  - filename
+patterns:
+  - regex: 'workflow_run'
+    flags: ''
+error_messages: []
+root_cause: |
+  The on.workflow_run.workflows: array matches against the target workflow's
+  top-level name: field — NOT the workflow's filename.
+
+  If the target workflow contains:
+    name: CI Pipeline
+
+  then the triggering workflow must specify:
+    on:
+      workflow_run:
+        workflows: ["CI Pipeline"]
+
+  Using the filename ("build.yml", "ci.yml", or ".github/workflows/ci.yml")
+  never matches when a name: field is present. The comparison is case-sensitive:
+  "CI" != "ci" != "Ci".
+
+  Secondary rule: if the target workflow has no name: field, GitHub uses the
+  workflow file path relative to the repo root as the match string (e.g.,
+  ".github/workflows/build.yml").
+
+  No error or warning is produced on mismatch — the triggering workflow
+  silently never fires. This is one of the most common workflow_run
+  misconfiguration patterns on Stack Overflow.
+fix: |
+  1. Open the target workflow file.
+  2. Find the top-level name: field. If absent, note the repo-relative path.
+  3. Use that exact string (case-sensitive) in the workflows: array.
+  4. Merge/deploy the triggering workflow to the default branch — workflow_run
+     only fires when the trigger configuration itself is on the default branch.
+fix_code:
+  - language: yaml
+    label: 'Correct: match the target workflow name: field exactly'
+    code: |
+      # Target workflow file: .github/workflows/ci.yml
+      name: CI Pipeline    # <-- this is what workflow_run matches on
+
+      on: [push]
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+      ---
+      # Triggering workflow file: .github/workflows/deploy.yml
+      on:
+        workflow_run:
+          workflows: ["CI Pipeline"]   # Must match name: exactly (not "ci.yml")
+          types: [completed]
+      jobs:
+        deploy:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+  - language: yaml
+    label: 'When target workflow has no name: field, use the file path'
+    code: |
+      # Target workflow has no name: field at .github/workflows/build.yml
+      on: [push]
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+      ---
+      # Triggering workflow must use the repo-relative path
+      on:
+        workflow_run:
+          workflows: [".github/workflows/build.yml"]
+          types: [completed]
+prevention:
+  - 'Always add a name: field to every workflow you intend to reference in workflow_run'
+  - 'Copy the name: value exactly (including capitalization and spaces) into workflows:'
+  - 'Add a comment in the triggering workflow citing which file the name came from'
+  - 'workflow_run silently never fires on name mismatches — no diagnostic is emitted'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs — workflow_run trigger'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name'
+    label: 'GitHub Docs — Workflow name: field'

package/package.json

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