@htekdev/actions-debugger 1.0.107 → 1.0.108

package/errors/caching-artifacts/cache-key-runner-os-insufficient-ubuntu-version-migration.yml

@@ -0,0 +1,90 @@
+id: caching-artifacts-063
+title: "runner.os insufficient in cache key after ubuntu-22.04 to ubuntu-24.04 migration — glibc-incompatible binaries silently restored"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache-key
+  - runner.os
+  - ubuntu-24.04
+  - binary-compatibility
+  - glibc
+  - migration
+patterns:
+  - regex: 'symbol lookup error.*undefined symbol'
+    flags: 'i'
+  - regex: 'version.*GLIBC.*not found'
+    flags: 'i'
+  - regex: 'GLIBCXX.*not found'
+    flags: 'i'
+error_messages:
+  - "symbol lookup error: ./bin/app: undefined symbol: __libc_single_threaded"
+  - "version `GLIBC_2.38' not found (required by ./bin/app)"
+  - "GLIBCXX_3.4.32 not found in /usr/lib/x86_64-linux-gnu/libstdc++.so.6"
+root_cause: |
+  `runner.os` returns "Linux" for ALL Linux-based GitHub-hosted runners regardless of
+  Ubuntu distribution version: ubuntu-22.04 (glibc 2.35, GCC 11) and ubuntu-24.04
+  (glibc 2.39, GCC 13) both return "Linux".
+
+  When a workflow migrates from `runs-on: ubuntu-22.04` to `runs-on: ubuntu-latest`
+  (which became ubuntu-24.04 in March 2025), cache keys using only `${{ runner.os }}`
+  continue to match previously saved caches from ubuntu-22.04. Compiled native binaries
+  — Rust/Cargo target directories, CMake build outputs, Go CGO artifacts, Python
+  Cython-compiled extensions, pre-built Node.js native addons — are restored from
+  the ubuntu-22.04 cache onto an ubuntu-24.04 runner.
+
+  Because ubuntu-24.04 ships a newer glibc (2.39 vs 2.35) and updated libstdc++, binaries
+  compiled against the older ABI fail at runtime with dynamic linker errors:
+
+    symbol lookup error: ./bin/app: undefined symbol: __libc_single_threaded
+    version `GLIBC_2.38' not found (required by ./bin/app)
+
+  The cache restore step succeeds and shows a green checkmark. The failure surfaces only
+  when the restored binary is executed later in the pipeline, potentially hours into a
+  build. Because the compile step is skipped (cache hit), the error appears to come from
+  the execution step with no indication that a stale cross-version cache is the cause.
+fix: |
+  Add the runner image version to the cache key so that binary artifacts are not shared
+  across different Ubuntu distribution versions. GitHub-hosted runners expose the image
+  version as the `ImageVersion` environment variable (e.g. "20250312.1"). Alternatively,
+  hash `/etc/os-release` as a portable OS version fingerprint.
+fix_code:
+  - language: yaml
+    label: "Include ImageVersion in cache key to isolate per Ubuntu release"
+    code: |
+      - name: Cache Cargo build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target/
+          # ImageVersion (e.g. "20250312.1") differs between ubuntu-22.04 and ubuntu-24.04
+          # Prevents restoring ubuntu-22.04 glibc-2.35 binaries on ubuntu-24.04 glibc-2.39
+          key: ${{ runner.os }}-${{ env.ImageVersion }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ env.ImageVersion }}-cargo-
+  - language: yaml
+    label: "Alternative: hash /etc/os-release for portable OS version fingerprint"
+    code: |
+      - name: Cache compiled artifacts
+        uses: actions/cache@v4
+        with:
+          path: build/
+          key: >-
+            ${{ runner.os }}-
+            ${{ hashFiles('/etc/os-release') }}-
+            cmake-${{ hashFiles('CMakeLists.txt', '**/CMakeLists.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ hashFiles('/etc/os-release') }}-cmake-
+prevention:
+  - "After migrating `runs-on` from a specific ubuntu version to `ubuntu-latest`, bust existing caches by adding a new key prefix or bumping a cache version counter"
+  - "Include `${{ env.ImageVersion }}` in cache keys whenever the cached content contains compiled native binaries"
+  - "Use `runner.arch` for x64/ARM64 differences and `ImageVersion` for OS version differences together for complete binary cache isolation"
+  - "Prefer caching dependency manifests and source-level artifacts over compiled binaries when cross-version compatibility is uncertain"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Actions — caching dependencies"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image specification (glibc and GCC versions)"
+  - url: "https://github.blog/changelog/2025-03-05-github-actions-ubuntu-latest-is-now-ubuntu-24-04/"
+    label: "GitHub Changelog — ubuntu-latest is now ubuntu-24.04 (March 2025)"

package/errors/permissions-auth/create-github-app-token-v2-default-single-repo-scope.yml

@@ -0,0 +1,70 @@
+id: permissions-auth-061
+title: "actions/create-github-app-token v2 — default token scope limited to current repository only"
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - create-github-app-token
+  - multi-repo
+  - token-scope
+  - v2-migration
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'actions/create-github-app-token@v2'
+    flags: 'i'
+error_messages:
+  - "Resource not accessible by integration"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+root_cause: |
+  actions/create-github-app-token underwent a breaking scope change in v2 (released 2024).
+
+  In v1: when no `repositories` input is specified, the generated token is scoped to ALL
+  repositories the GitHub App installation has access to.
+
+  In v2: when no `repositories` or `owner` input is specified, the token is scoped ONLY
+  to the current repository where the workflow is running. This matches the GitHub App
+  installation token API default behavior when requesting a per-repository token.
+
+  Workflows that used v1 and relied on the token to access other repositories (for
+  cross-repo clones, API calls, pushes, or artifact publishing) silently receive a
+  limited-scope token in v2. Operations on other repos return "Resource not accessible
+  by integration" or "HTTP 404 Not Found" with no clear indication that a v2 migration
+  caused the regression.
+fix: |
+  Explicitly declare the repositories the token should cover using the `repositories`
+  input (comma-separated repository names, without the org prefix). To grant access to
+  all repositories the app has access to within the same organization, use the `owner`
+  input instead.
+fix_code:
+  - language: yaml
+    label: "Explicit multi-repo token scope (v2)"
+    code: |
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+          # List every repository the token needs access to
+          repositories: "repo-a,repo-b,infra-configs"
+  - language: yaml
+    label: "Org-wide token scope using owner input (v2)"
+    code: |
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+          # Grants access to all repos the app has access to in the org
+          owner: ${{ github.repository_owner }}
+prevention:
+  - "When upgrading from v1 to v2, audit all usages for cross-repo operations and add an explicit `repositories:` or `owner:` input"
+  - "Pin to a major version tag and review the CHANGELOG before upgrading any action that generates authentication tokens"
+  - "Test cross-repo operations in a staging workflow immediately after a major version upgrade"
+docs:
+  - url: "https://github.com/actions/create-github-app-token/releases/tag/v2.0.0"
+    label: "actions/create-github-app-token v2.0.0 release notes (scope change)"
+  - url: "https://github.com/actions/create-github-app-token/blob/main/README.md#inputs"
+    label: "actions/create-github-app-token README — repositories and owner inputs"

package/errors/silent-failures/github-event-head-commit-null-non-push-events.yml

@@ -0,0 +1,99 @@
+id: silent-failures-095
+title: "github.event.head_commit is null on non-push events — commit message checks silently return false"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - head-commit
+  - workflow-dispatch
+  - event-context
+  - commit-message
+  - null-context
+patterns:
+  - regex: 'github\.event\.head_commit\.message'
+    flags: 'i'
+  - regex: 'github\.event\.head_commit\b'
+    flags: 'i'
+error_messages:
+  - "contains(github.event.head_commit.message, ...) returns false on workflow_dispatch"
+  - "github.event.head_commit is null"
+root_cause: |
+  The `github.event.head_commit` context object is only populated on `push` events.
+  On all other trigger types — `workflow_dispatch`, `pull_request`, `pull_request_target`,
+  `schedule`, `workflow_call`, `workflow_run`, `release`, and others — the property is
+  null, and all child fields evaluate to empty string `""` in expressions.
+
+  A very common workflow pattern is to gate deployment or release steps based on the
+  commit message:
+
+    if: contains(github.event.head_commit.message, '[deploy]')
+
+  When this condition is evaluated on a `workflow_dispatch` run, a scheduled run, or
+  any non-push trigger, `github.event.head_commit` is null and `contains()` receives
+  an empty string. The expression silently returns false and the step is skipped.
+
+  No error, no warning, and no indication in the workflow log that the condition was
+  never evaluated against real commit message data. Developers manually triggering the
+  workflow see their step silently skipped with no explanation.
+
+  This is particularly confusing because:
+  - The workflow completes successfully with a green checkmark
+  - The step appears in the log as skipped with no reason given
+  - Manual `workflow_dispatch` runs show no null-context warning
+fix: |
+  Guard the commit message check with an explicit event type condition, or provide a
+  workflow_dispatch input as an equivalent gate for manual runs.
+fix_code:
+  - language: yaml
+    label: "Guard commit message check to push events only"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy on tagged commit message
+              # Only evaluate head_commit.message on push events where it is defined
+              if: >-
+                github.event_name == 'push' &&
+                contains(github.event.head_commit.message, '[deploy]')
+              run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Support push and manual dispatch with input fallback"
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+          inputs:
+            deploy:
+              description: 'Trigger deployment manually'
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Resolve deploy flag
+              id: flag
+              run: |
+                if [[ "${{ github.event_name }}" == "push" ]]; then
+                  MSG="${{ github.event.head_commit.message }}"
+                  echo "enabled=$([[ "$MSG" == *'[deploy]'* ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+                else
+                  echo "enabled=${{ inputs.deploy }}" >> $GITHUB_OUTPUT
+                fi
+
+            - name: Deploy
+              if: steps.flag.outputs.enabled == 'true'
+              run: ./scripts/deploy.sh
+prevention:
+  - "Never use `github.event.head_commit.*` without first checking `github.event_name == 'push'`"
+  - "Use `workflow_dispatch` inputs with boolean type as the manual-trigger equivalent of commit-message gates"
+  - "Document which events activate each step — add inline comments explaining gating conditions"
+  - "Test multi-trigger workflows by manually running them and verifying steps behave as expected"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Actions push event — head_commit availability"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/contexts#github-context"
+    label: "GitHub context reference — github.event object"

package/errors/silent-failures/timeout-minutes-result-cancelled-not-failure.yml

@@ -0,0 +1,95 @@
+id: silent-failures-096
+title: "Job timeout-minutes sets result to 'cancelled' not 'failure' — if: failure() notification jobs silently skip timed-out jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - timeout-minutes
+  - job-result
+  - if-failure
+  - notification
+  - cancelled
+  - cleanup-job
+patterns:
+  - regex: 'if:.*failure\(\)'
+    flags: 'i'
+  - regex: 'timeout-minutes:\s*\d+'
+    flags: 'i'
+error_messages:
+  - "This step was skipped because a previous step failed"
+  - "notification job skipped — upstream job timed out but result is 'cancelled' not 'failure'"
+root_cause: |
+  When a job exceeds its `timeout-minutes:` limit, GitHub Actions cancels the job and
+  sets its `result` to `"cancelled"` — NOT `"failure"`. This is a consistent but
+  widely misunderstood behavior.
+
+  A standard pattern is to add a notification or cleanup job that runs when builds fail:
+
+    notify:
+      needs: build
+      if: failure()
+      runs-on: ubuntu-latest
+
+  The `failure()` status check function returns true only when at least one upstream job
+  has result `"failure"`. It does NOT match `"cancelled"`. When `build` times out,
+  `needs.build.result` is `"cancelled"`, so `if: failure()` evaluates to false and
+  the notification job is silently skipped.
+
+  The four terminal job result values are: "success", "failure", "cancelled", "skipped".
+  The built-in functions map to:
+  - `failure()` → true when any upstream job result is "failure"
+  - `cancelled()` → true when any upstream job result is "cancelled"
+  - `success()` → true when all upstream jobs result in "success" (default)
+  - `always()` → always true regardless of upstream results
+
+  Developers are often surprised that a timed-out build does not trigger their alerting
+  job. The UI shows the timed-out job in orange ("Cancelled"), while the notification
+  job appears grey ("Skipped") — there is no direct indication that the skip is due to
+  the timeout rather than an unrelated condition.
+fix: |
+  Expand the notification job condition to explicitly cover both `failure` and `cancelled`
+  results, using `always()` to ensure the job runs regardless of upstream outcomes.
+fix_code:
+  - language: yaml
+    label: "Catch both failure and timeout (cancelled) in notification job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+
+        notify:
+          needs: build
+          # Use always() so the job runs; then check for failure OR cancelled (timeout)
+          if: always() && (needs.build.result == 'failure' || needs.build.result == 'cancelled')
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send alert
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # call your notification webhook here
+  - language: yaml
+    label: "Multi-job pipeline — catch any non-success terminal state"
+    code: |
+      jobs:
+        report:
+          needs: [build, test, deploy]
+          if: >-
+            always() &&
+            (contains(needs.*.result, 'failure') ||
+             contains(needs.*.result, 'cancelled'))
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Pipeline did not complete successfully"
+prevention:
+  - "Replace bare `if: failure()` with `if: always() && (needs.X.result == 'failure' || needs.X.result == 'cancelled')` whenever upstream jobs have `timeout-minutes:` set"
+  - "Treat `timeout-minutes` as a cancellation mechanism — timed-out jobs report `cancelled` not `failure`"
+  - "Test your notification path by temporarily reducing `timeout-minutes` to confirm the alerting logic fires on timeout"
+  - "Document in team runbooks that CI timeouts appear orange ('Cancelled') not red ('Failed') in the Actions UI"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "GitHub Actions — status check functions (failure, cancelled, always)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes"
+    label: "GitHub Actions workflow syntax — timeout-minutes"

package/package.json

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