@htekdev/actions-debugger 1.0.41 → 1.0.42

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/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/package.json

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