@htekdev/actions-debugger 1.0.100 → 1.0.102

package/errors/caching-artifacts/caching-artifacts-056.yml

@@ -0,0 +1,113 @@
+id: caching-artifacts-056
+title: 'actions/cache v1 and v2 deprecated — workflows fail hard with "automatically failed" error'
+category: caching-artifacts
+severity: error
+tags:
+  - actions/cache
+  - deprecated
+  - v1
+  - v2
+  - hard-failure
+  - breaking-change
+  - upgrade
+patterns:
+  - regex: 'automatically failed.*deprecated version.*actions/cache'
+    flags: 'i'
+  - regex: 'deprecated version of.{0,30}actions/cache'
+    flags: 'i'
+  - regex: 'actions/cache@v[12]\b'
+    flags: 'i'
+error_messages:
+  - "This request has been automatically failed because it uses a deprecated version of `actions/cache: 6849a6489940f00c2f30c0fb92c6274307ccb58a`"
+  - "Error: This request has been automatically failed because it uses a deprecated version of `actions/cache`"
+root_cause: |
+  GitHub announced in December 2024 (GitHub Changelog) that `actions/cache` versions 1 and 2
+  were deprecated and would be hard-failed starting February 1, 2025. Any workflow still
+  pinned to `actions/cache@v1` or `actions/cache@v2` (or to a full SHA that resolves to
+  those versions) now fails immediately with a hard error — no cache operation is attempted
+  and the entire step fails.
+
+  The error message includes the SHA of the deprecated action version:
+    "This request has been automatically failed because it uses a deprecated version
+    of `actions/cache: <SHA>`"
+
+  This is a hard failure, not a graceful degradation — the step exit code is non-zero and
+  causes the job to fail unless `continue-on-error: true` is set on the step (which is
+  not a recommended fix).
+
+  Common reasons workflows are still on v1/v2:
+  1. The workflow was written years ago and never updated
+  2. The action is referenced by a full commit SHA from before v3 was released
+  3. A reusable workflow or composite action calls an outdated dependency that pins v1/v2
+  4. `Dependabot` is not enabled on the repo for GitHub Actions
+
+  Note: `actions/cache@v3` and `actions/cache@v4` are both supported. V4 is the current
+  recommended version.
+fix: |
+  Upgrade all `actions/cache` references from v1 or v2 to v4 (recommended) or v3.
+  Search your repository for `actions/cache@v1` and `actions/cache@v2` references,
+  including in nested composite actions and reusable workflows.
+
+  If you are migrating from v3 to v4, note the breaking changes documented in the
+  v3-to-v4 migration guide (see caching-artifacts-009). The v1/v2 to v4 migration
+  follows the same v3-to-v4 guidance since v3 and v4 share the same input API except
+  for `save-always`.
+
+  Enable Dependabot for GitHub Actions updates to automatically receive future
+  deprecation PRs.
+fix_code:
+  - language: yaml
+    label: 'Problem: workflow pinned to deprecated actions/cache v1 or v2'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        # FAILS: v1 and v2 are deprecated — hard failure since Feb 1, 2025
+        - uses: actions/cache@v1
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+
+        # Also fails — v2 is deprecated
+        - uses: actions/cache@v2
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+  - language: yaml
+    label: 'Fix: upgrade to actions/cache v4 (recommended)'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        # CORRECT: use v4 (or v3 if v3-to-v4 migration is not yet done)
+        - uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-npm-
+  - language: yaml
+    label: 'Dependabot config to automatically receive Actions version updates'
+    code: |
+      # .github/dependabot.yml
+      version: 2
+      updates:
+        - package-ecosystem: github-actions
+          directory: /
+          schedule:
+            interval: weekly
+          # Dependabot will open PRs to upgrade actions/cache@v1/v2 → v4 automatically
+prevention:
+  - "Enable Dependabot for GitHub Actions in `.github/dependabot.yml` to receive automated upgrade PRs."
+  - "Search your `.github/workflows/` directory for `actions/cache@v1` and `actions/cache@v2` before the deprecation deadline."
+  - "Check composite actions and reusable workflows — they may internally call deprecated cache versions."
+  - "Audit SHA-pinned action references to ensure the SHA does not point to a v1/v2 release."
+docs:
+  - url: 'https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions/#actions-cache-v1-v2-and-actions-toolkit-cache-package-closing-down'
+    label: 'GitHub Changelog Dec 2024: actions/cache v1/v2 deprecation notice'
+  - url: 'https://github.com/actions/cache/discussions/1510'
+    label: 'actions/cache Discussion #1510: deprecated version hard failure reports'
+  - url: 'https://github.com/actions/cache'
+    label: 'actions/cache repository — upgrade instructions'
+  - url: 'https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot'
+    label: 'GitHub Docs: Keeping your actions up to date with Dependabot'

package/errors/caching-artifacts/caching-artifacts-057.yml

@@ -0,0 +1,98 @@
+id: caching-artifacts-057
+title: '`actions/cache` Never Refreshes Cached Content — Cache Keys Are Immutable Once Stored'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - stale
+  - immutable
+  - cache-hit
+  - refresh
+  - node-modules
+patterns:
+  - regex: 'cache-hit.*true.*post.*skip'
+    flags: 'i'
+error_messages:
+  - "Cache hit occurred on the primary key, not saving cache."
+  - "Cache hit occurred on the primary key runner-os-node-"
+root_cause: |
+  `actions/cache` uses immutable cache keys. Once a cache entry is stored for a given
+  key, it cannot be updated or overwritten — any subsequent run that produces an exact
+  key match will restore the cached content and the post step will NOT save a new cache
+  entry because one already exists for that key.
+
+  This means cached content (node_modules, pip packages, Maven artifacts, etc.) is
+  frozen at the point of first creation and will not reflect package updates until:
+  - The cache entry expires (GitHub-hosted caches expire after 7 days of no access)
+  - The cache key changes (e.g., lockfile hash changes)
+  - The cache entry is manually deleted via the GitHub UI or API
+
+  Common misconception: developers expect that running `npm ci` inside a cached
+  node_modules hit will update the cache if packages changed. It won't. The cache key
+  (usually `${{ hashFiles('package-lock.json') }}`) must change for a new cache to be
+  saved.
+
+  Related gotcha: if restore-keys produce a partial hit (different key prefix), the
+  post step DOES save a new cache — but for the full key, not the partial restore key.
+  This creates unexpected cache churn from the developer's perspective where cache hit
+  rate is high but actual content is outdated.
+
+  This is intentional GitHub design but frequently misunderstood, leading to:
+  - Stale node_modules with old transitive dependencies
+  - pip packages that don't receive security patches within 7 days
+  - Build artifacts compiled against old toolchain versions
+fix: |
+  To force periodic cache refresh without changing your lockfile, use one of these patterns:
+
+  1. Include a date-based component in the cache key (weekly rotation).
+  2. Use `actions/cache/restore` + `actions/cache/save` with explicit control of when
+     to save (allows saving even on hits).
+  3. Delete the cache manually via GitHub UI (Actions > Caches) or the API when you
+     need an immediate refresh.
+fix_code:
+  - language: yaml
+    label: "Weekly-rotating cache key to prevent indefinitely stale caches"
+    code: |
+      - name: Get week number for cache rotation
+        id: date
+        run: echo "week=$(date +'%Y-%U')" >> "$GITHUB_OUTPUT"
+
+      - name: Cache node_modules (refreshes weekly)
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ steps.date.outputs.week }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ steps.date.outputs.week }}-
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: "Separate restore + save for explicit cache update control"
+    code: |
+      - name: Restore cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node-
+
+      - run: npm ci
+
+      - name: Save updated cache (always saves, even on hit)
+        uses: actions/cache/save@v4
+        if: always()
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}-${{ github.run_id }}
+prevention:
+  - "Understand that GitHub cache keys are immutable — a key that already exists in the cache will never be overwritten"
+  - "Use time-based or run-id-based cache key suffixes when cached content must be refreshed more frequently than lockfile changes"
+  - "Monitor cache age in the GitHub UI (Actions > Caches) and manually purge entries that appear stale"
+  - "For security-sensitive dependencies, prefer short cache TTLs via run-id keys or disable caching entirely"
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs — Caching dependencies to speed up workflows"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache tips and workarounds"
+  - url: "https://github.com/actions/cache/issues/1380"
+    label: "actions/cache #1380 — cache never updates on key hit"

package/errors/permissions-auth/permissions-auth-059.yml

@@ -0,0 +1,136 @@
+id: permissions-auth-059
+title: 'GITHUB_TOKEN expires after 24 hours on self-hosted runners — long-running jobs fail with "GITHUB_TOKEN has expired"'
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - token-expiry
+  - self-hosted-runner
+  - long-running-jobs
+  - 24-hour-limit
+  - authentication
+patterns:
+  - regex: 'GITHUB_TOKEN has expired'
+    flags: 'i'
+  - regex: 'Unable to extend GITHUB_TOKEN expiration'
+    flags: 'i'
+  - regex: 'token.*expired.*self.hosted'
+    flags: 'i'
+error_messages:
+  - "Unable to extend GITHUB_TOKEN expiration time due to: GITHUB_TOKEN has expired."
+  - "Error: fatal: unable to access 'https://github.com/...': The requested URL returned error: 403"
+root_cause: |
+  `GITHUB_TOKEN` is an installation access token issued at the START of each job. Its
+  lifetime is tied to the job execution, with a hard cap determined by the runner type:
+
+  - **GitHub-hosted runners**: `GITHUB_TOKEN` lives for up to 6 hours (matching the maximum
+    job execution time). On hosted runners this limit is never the issue because the job
+    itself can't run longer than 6 hours.
+
+  - **Self-hosted runners**: Jobs can run for up to 5 days, but `GITHUB_TOKEN` can only be
+    refreshed for up to **24 hours**. If a job on a self-hosted runner exceeds 24 hours of
+    runtime, any subsequent GitHub API call, `git push`, `gh` CLI invocation, or action that
+    uses `${{ github.token }}` or `${{ secrets.GITHUB_TOKEN }}` will fail with a 401/403
+    authentication error.
+
+  The specific error message is:
+    "Unable to extend GITHUB_TOKEN expiration time due to: GITHUB_TOKEN has expired."
+
+  This is particularly common in:
+  - Large test suites or build pipelines that process massive monorepos
+  - ML/data pipelines that process large datasets sequentially
+  - Long-running deployment or migration jobs that need GitHub API access at the end
+  - Jobs with retries that collectively exceed 24 hours
+
+  Note: `actions/create-github-app-token` GitHub App tokens have a similar but shorter
+  1-hour expiry — see permissions-auth-046 for that pattern.
+fix: |
+  Several approaches, in order of recommendation:
+
+  1. **Split the job into smaller jobs** — Break the long-running job into multiple shorter
+     jobs connected by `needs:` dependencies. Each job gets its own fresh `GITHUB_TOKEN`.
+
+  2. **Use a GitHub App token** — Use `actions/create-github-app-token` to generate tokens
+     mid-job as needed, or generate a fresh token at the point in the job where you need it.
+
+  3. **Use a PAT (Personal Access Token)** — Store a long-lived PAT in repository or
+     organization secrets and use it in place of `GITHUB_TOKEN` for the API calls at the
+     end of the long-running job. PATs do not expire in 24 hours (they expire based on the
+     PAT expiration date you set). Drawback: PATs are tied to a specific user account.
+
+  4. **Use a machine user PAT** — Create a dedicated machine account and use its PAT.
+     This decouples the secret from any individual developer's account.
+fix_code:
+  - language: yaml
+    label: 'Problem: long-running self-hosted job uses GITHUB_TOKEN after 24+ hours'
+    code: |
+      jobs:
+        long-build:
+          runs-on: [self-hosted, large-runner]
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run 26-hour data processing
+              run: ./scripts/process_all_data.sh   # takes ~26 hours
+
+            # FAILS: GITHUB_TOKEN has expired by the time this step runs
+            - name: Upload results to GitHub
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: gh release upload v1.0 ./output/*.tar.gz
+  - language: yaml
+    label: 'Fix: split into jobs so each gets a fresh GITHUB_TOKEN'
+    code: |
+      jobs:
+        process-data:
+          runs-on: [self-hosted, large-runner]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/process_all_data.sh
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output-files
+                path: ./output/
+
+        upload-release:
+          needs: process-data
+          runs-on: ubuntu-latest     # hosted runner with fresh token
+          permissions:
+            contents: write
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: output-files
+                path: ./output/
+            # GITHUB_TOKEN is fresh — just issued for this new job
+            - name: Upload to release
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: gh release upload v1.0 ./output/*.tar.gz
+  - language: yaml
+    label: 'Fix: use stored PAT when splitting jobs is not feasible'
+    code: |
+      jobs:
+        long-build:
+          runs-on: [self-hosted, large-runner]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/process_all_data.sh
+
+            # Use a PAT stored in secrets — does not expire in 24 hours
+            - name: Upload results (using PAT)
+              env:
+                GH_TOKEN: ${{ secrets.MACHINE_USER_PAT }}   # PAT, not github.token
+              run: gh release upload v1.0 ./output/*.tar.gz
+prevention:
+  - "Design self-hosted runner jobs to complete within 24 hours, or split them into smaller jobs connected by `needs:`."
+  - "If a job genuinely requires >24 hours of runtime, use a PAT or GitHub App token for API calls instead of `GITHUB_TOKEN`."
+  - "Add a monitoring step that logs elapsed job time — alert if a job approaches 20+ hours."
+  - "Avoid using `GITHUB_TOKEN` for API calls near the end of jobs that are known to run close to the 24-hour limit."
+  - "For GitHub-hosted runners this is not an issue — the job execution limit (6 hours) is shorter than the token lifetime."
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#about-the-github_token-secret'
+    label: 'GitHub Docs: GITHUB_TOKEN — effective maximum lifetime'
+  - url: 'https://stackoverflow.com/questions/75602556/how-can-i-use-a-github-token-for-more-than-24-hours'
+    label: 'Stack Overflow: How to use GITHUB_TOKEN for more than 24 hours'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits'
+    label: 'GitHub Docs: Self-hosted runner usage limits (5-day job limit)'

package/errors/permissions-auth/permissions-auth-060.yml

@@ -0,0 +1,115 @@
+id: permissions-auth-060
+title: 'Fork Pull Request Workflows Cannot Access Repository Secrets — Secrets Context Is Empty'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - fork
+  - pull-request
+  - secrets
+  - security
+  - workflow-permissions
+patterns:
+  - regex: 'secrets\.[\w_]+.*empty|secrets context.*fork'
+    flags: 'i'
+error_messages:
+  - "Error: Input required and not supplied: token"
+  - "HttpError: Bad credentials"
+  - "Error: Resource not accessible by integration"
+root_cause: |
+  GitHub's security model prevents workflows triggered by `pull_request` events from
+  fork repositories from accessing repository secrets. This applies to ALL non-Dependabot
+  external contributor forks — not just Dependabot.
+
+  When a fork PR workflow runs:
+  - All `secrets.*` values resolve to empty string `''`
+  - `secrets.GITHUB_TOKEN` is replaced with a read-only token scoped only to the fork
+    repository (cannot write to the upstream repo, cannot access packages, etc.)
+  - Environment secrets are also unavailable
+  - Fine-grained PATs stored as secrets are unavailable
+
+  This is intentional — allowing forks to read secrets would enable malicious PRs to
+  exfiltrate credentials.
+
+  Common failure patterns:
+  - `actions/setup-node` with `registry-url` + `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` → 401 Unauthorized
+  - `docker/login-action` with `${{ secrets.DOCKERHUB_TOKEN }}` → login fails silently, image push 403
+  - `aws-actions/configure-aws-credentials` with role ARN from secrets → empty role, OIDC fallback
+  - Custom actions reading a `token:` input wired to `${{ secrets.MY_TOKEN }}` → action receives ''
+    and may throw "Input required and not supplied: token"
+
+  The fork PR restriction also applies to `workflow_dispatch` when triggered from a fork,
+  and to `check_suite`/`check_run` events from fork PRs.
+
+  Note: `pull_request_target` DOES have access to secrets because it runs in the context
+  of the BASE repository — but this introduces a different security risk (running untrusted
+  code with secret access) that requires careful mitigation.
+fix: |
+  For CI checks that don't need secrets (lint, unit tests, build validation), no change
+  is needed — the read-only GITHUB_TOKEN is sufficient.
+
+  For steps that require secrets:
+
+  1. Gate secret-requiring steps on `github.event.pull_request.head.repo.fork == false`
+     to skip them on fork PRs gracefully.
+  2. Use `pull_request_target` + a separate privileged job for publishing/deploying,
+     but ALWAYS check out from `github.event.pull_request.head.sha` explicitly and
+     never run untrusted code in the same job.
+  3. For package publishing, only publish from base branch pushes (not from PRs at all).
+fix_code:
+  - language: yaml
+    label: "Skip secret-requiring steps on fork PRs gracefully"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests (works on fork PRs)
+              run: npm test
+
+            - name: Publish coverage report (skip on fork PRs)
+              if: github.event.pull_request.head.repo.fork == false
+              env:
+                CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+              run: npx codecov
+  - language: yaml
+    label: "Split fork-safe CI from privileged deployment using workflow_run"
+    code: |
+      # workflow: ci.yml — runs on all PRs including forks (no secrets needed)
+      on:
+        pull_request:
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+      ---
+      # workflow: publish-coverage.yml — runs after ci.yml completes (has secrets)
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+      jobs:
+        coverage:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Publish coverage
+              env:
+                CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+              run: echo "Publishing coverage for run ${{ github.event.workflow_run.id }}"
+prevention:
+  - "Design CI workflows to not require secrets for the build/test steps — secrets should only be needed for publish/deploy"
+  - "Check `github.event.pull_request.head.repo.fork` before any step that uses secrets to provide a clear skip message"
+  - "Do not use `pull_request_target` as a shortcut to get secrets — it runs untrusted fork code with base repo privileges, creating a severe injection risk"
+  - "Use `workflow_run` to chain a privileged follow-up workflow that runs in base repo context after fork CI succeeds"
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections"
+    label: "GitHub Docs — Security hardening: fork PR and secret access"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request"
+    label: "GitHub Docs — pull_request event: fork limitations"
+  - url: "https://securitylab.github.com/research/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab — Preventing pwn requests (pull_request_target risks)"

package/errors/runner-environment/homebrew-auto-update-macos-ci-slow.yml

@@ -0,0 +1,84 @@
+id: runner-environment-172
+title: 'Homebrew 4.x triggers auto-update on every brew install, adding 1-3 minutes to macOS CI'
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - homebrew
+  - brew
+  - slow-ci
+  - performance
+  - HOMEBREW_NO_AUTO_UPDATE
+patterns:
+  - regex: '==> Auto-updated Homebrew!|Updating Homebrew\.\.\.|Auto-update took'
+    flags: 'i'
+  - regex: 'Fetching https://formulae\.brew\.sh/api/(formula|cask)\.jws\.json'
+    flags: 'i'
+error_messages:
+  - "==> Auto-updated Homebrew!"
+  - "Updating Homebrew..."
+  - "Fetching https://formulae.brew.sh/api/formula.jws.json"
+  - "This operation has taken more than 5 minutes"
+root_cause: |
+  Homebrew 4.0 (released February 2023) replaced its previous approach of cloning the
+  homebrew-core and homebrew-cask Git repositories with downloading pre-computed JSON API
+  responses from formulae.brew.sh. While this reduced the on-disk size of the Homebrew
+  installation, Homebrew retained its auto-update behavior: by default, any brew install,
+  brew upgrade, or brew reinstall command triggers an auto-update check if the local
+  formula cache is older than HOMEBREW_AUTO_UPDATE_SECS (default: 300 seconds = 5 minutes).
+
+  On GitHub-hosted macOS runners, every fresh runner starts with a Homebrew installation
+  that has not been updated recently, so the first brew install in any job always triggers
+  a full API fetch from formulae.brew.sh. This fetch downloads large JSON manifests for
+  formula and cask databases and typically adds 1-3 minutes to the job. For workflows with
+  multiple parallel matrix jobs or multiple brew install calls, this overhead compounds.
+
+  Homebrew 4.x also added HOMEBREW_AUTO_UPDATE_SECS and related env vars to control this
+  behavior, but the default settings cause every fresh runner to update on first use.
+fix: |
+  Set HOMEBREW_NO_AUTO_UPDATE=1 as a workflow environment variable to disable automatic
+  updates entirely. The macOS runner image ships a recent-enough Homebrew installation for
+  most use cases. If you need the absolute latest formula versions for a specific tool,
+  run a single explicit brew update at the start of the job.
+
+  Also set HOMEBREW_NO_INSTALL_CLEANUP=1 to prevent cleanup passes that extend install time.
+fix_code:
+  - language: yaml
+    label: 'Disable Homebrew auto-update at workflow level (recommended)'
+    code: |
+      env:
+        HOMEBREW_NO_AUTO_UPDATE: '1'
+        HOMEBREW_NO_INSTALL_CLEANUP: '1'
+
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install build dependencies
+              run: brew install ninja cmake
+  - language: yaml
+    label: 'Run one explicit update then suppress auto-update per job'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          env:
+            HOMEBREW_NO_AUTO_UPDATE: '1'
+            HOMEBREW_NO_INSTALL_CLEANUP: '1'
+          steps:
+            - name: Update Homebrew (once, explicit)
+              run: brew update
+            - name: Install tools
+              run: brew install ninja cmake
+prevention:
+  - 'Set HOMEBREW_NO_AUTO_UPDATE=1 and HOMEBREW_NO_INSTALL_CLEANUP=1 as top-level workflow env vars'
+  - 'Use actions/setup-* official actions instead of brew install when available (setup-python, setup-node, etc.)'
+  - 'Cache brew downloads using actions/cache with a key derived from a Brewfile or explicit package list'
+  - 'Set HOMEBREW_AUTO_UPDATE_SECS=86400 to limit auto-updates to at most once per day if you need periodic updates'
+docs:
+  - url: 'https://docs.brew.sh/Manpage#environment'
+    label: 'Homebrew environment variables — HOMEBREW_NO_AUTO_UPDATE'
+  - url: 'https://brew.sh/2023/02/16/homebrew-4.0.0/'
+    label: 'Homebrew 4.0.0 release notes — JSON API migration'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md'
+    label: 'macOS 15 runner image — preinstalled Homebrew version'

package/errors/runner-environment/python312-ast-str-num-removed-ubuntu24.yml

@@ -0,0 +1,74 @@
+id: runner-environment-171
+title: 'Python 3.12 removes deprecated ast.Str, ast.Num, ast.NameConstant on ubuntu-24.04 — older linters crash'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - python
+  - python-3.12
+  - ast
+  - linting
+  - pylint
+  - bandit
+patterns:
+  - regex: 'AttributeError: module ''ast'' has no attribute ''(Str|Num|NameConstant|Bytes)'''
+    flags: 'i'
+  - regex: 'ImportError.*pylint|cannot import name.*astroid|AttributeError.*ast\.(Str|Num)'
+    flags: 'i'
+error_messages:
+  - "AttributeError: module 'ast' has no attribute 'Str'"
+  - "AttributeError: module 'ast' has no attribute 'Num'"
+  - "AttributeError: module 'ast' has no attribute 'NameConstant'"
+  - "AttributeError: module 'ast' has no attribute 'Bytes'"
+root_cause: |
+  Ubuntu 24.04 ships Python 3.12 as the default system Python (/usr/bin/python3).
+  Python 3.12 permanently removed several deprecated AST node types that were soft-deprecated
+  since Python 3.8 and slated for removal in 3.12: ast.Str, ast.Num, ast.NameConstant,
+  ast.Bytes, and the legacy constant-value wrapper nodes.
+
+  Many popular static analysis tools directly referenced these internal AST nodes for
+  backward compatibility with Python 2 and early Python 3 code. Affected tools include:
+  - pylint < 3.0 (uses astroid which references ast.Str/ast.Num for constant folding)
+  - astroid < 3.0 (core dependency of pylint; crash on import with Python 3.12)
+  - bandit < 1.8.0 (security linter; uses ast.Str for string literal detection)
+  - flake8-bugbear < 23.x (some plugin versions reference ast.Num directly)
+  - pyflakes < 3.0 (uses ast.Str for format string analysis)
+
+  Workflows that install these linters without pinning minimum versions fail immediately
+  when the runner migrates from ubuntu-22.04 (Python 3.10) to ubuntu-24.04 (Python 3.12).
+  The error surfaces as an AttributeError during tool import, before any code is analyzed.
+fix: |
+  Upgrade the affected analysis tools to Python 3.12-compatible versions:
+  - pylint: upgrade to 3.0+ (requires astroid >= 3.0 simultaneously)
+  - bandit: upgrade to 1.8.0+
+  - flake8: upgrade to 7.0+ with compatible plugin versions
+
+  If an immediate upgrade is not feasible, pin the runner to ubuntu-22.04 (Python 3.10)
+  temporarily while the upgrade is planned. Ubuntu 22.04 runner support continues until
+  at least April 2027.
+fix_code:
+  - language: yaml
+    label: 'Upgrade linting tools to Python 3.12-compatible versions'
+    code: |
+      - name: Install Python linters (3.12 compatible)
+        run: pip install 'pylint>=3.0' 'astroid>=3.0' 'bandit>=1.8.0' 'flake8>=7.0'
+  - language: yaml
+    label: 'Temporary workaround — pin to ubuntu-22.04 (Python 3.10)'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-22.04  # Python 3.10 — avoids ast.Str removal in 3.12
+prevention:
+  - 'Pin minimum versions for linting tools in requirements-dev.txt or pyproject.toml'
+  - 'Use actions/setup-python to control the Python version explicitly rather than relying on system Python'
+  - 'Test your CI toolchain against Python 3.12 before migrating to ubuntu-24.04'
+  - 'Review the Python 3.12 changelog for all removed deprecated features before upgrading'
+docs:
+  - url: 'https://docs.python.org/3.12/whatsnew/3.12.html#removed'
+    label: 'Python 3.12 Removed Features'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'Ubuntu 24.04 runner image software listing'
+  - url: 'https://pylint.readthedocs.io/en/stable/whatsnew/3.0/summary.html'
+    label: 'Pylint 3.0 migration and Python 3.12 compatibility notes'
+  - url: 'https://github.com/PyCQA/bandit/releases/tag/1.8.0'
+    label: 'bandit 1.8.0 release notes — Python 3.12 AST compatibility'

package/errors/runner-environment/runner-environment-170.yml

@@ -0,0 +1,93 @@
+id: runner-environment-170
+title: 'windows-latest Migration to Windows Server 2025 Removes MSVC v142 (VS 2019) Toolchain'
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - msvc
+  - cmake
+  - msbuild
+  - toolchain
+  - migration
+patterns:
+  - regex: 'MSB8020.*v142.*cannot be found'
+    flags: 'i'
+  - regex: 'build tools for v142.*Platform Toolset.*v142.*cannot be found'
+    flags: 'i'
+  - regex: 'CMAKE_GENERATOR_TOOLSET.*v142.*not found'
+    flags: 'i'
+error_messages:
+  - "MSBUILD : error MSB8020: The build tools for v142 (Platform Toolset = 'v142') cannot be found."
+  - "CMake Error: The CMAKE_CXX_COMPILER: cl.exe is not able to compile a simple test program."
+  - "error MSB8020: The build tools for v142 (Platform Toolset = 'v142') cannot be found."
+root_cause: |
+  Starting November 2024, `windows-latest` was migrated to Windows Server 2025 with
+  Visual Studio 2022 17.12 as the default build environment. Windows Server 2025 runner
+  images do not include the Visual Studio 2019 build tools (MSVC v142 / toolset 14.2).
+
+  Projects that explicitly request the VS 2019 toolchain via any of these mechanisms fail:
+  - MSBuild `<PlatformToolset>v142</PlatformToolset>` in .vcxproj files
+  - CMake `-T v142` flag or `set(CMAKE_GENERATOR_TOOLSET v142)` in CMakeLists.txt
+  - MSBuild command-line flag `/p:PlatformToolset=v142`
+  - Visual Studio solution files pinned to VS 2019 (toolset version 142)
+
+  Windows Server 2022 runners (`windows-2022`) continue to offer both VS 2019
+  (v142) and VS 2022 (v143) toolchains in parallel. After the `windows-latest`
+  migration, workflows that did not pin to `windows-2022` and relied on v142
+  break silently on runners already migrated while appearing to work in older
+  runner pools.
+
+  The migration timeline:
+  - Nov 2024: windows-latest begins pointing to Windows Server 2025 (partial rollout)
+  - Early 2025: Full rollout; all new `windows-latest` queue jobs use WS 2025
+
+  Reference: https://github.com/actions/runner-images/issues/10751
+fix: |
+  Choose one of the following approaches:
+
+  1. Upgrade to the v143 (VS 2022) toolchain — recommended for long-term compatibility.
+  2. Pin to `windows-2022` runner if you cannot migrate immediately.
+  3. Install the VS 2019 build tools component manually (slow, increases job time).
+fix_code:
+  - language: yaml
+    label: "Option A: upgrade toolchain to v143 (VS 2022) in CMakeLists.txt"
+    code: |
+      # In CMakeLists.txt — remove explicit toolset pinning
+      # cmake_minimum_required(VERSION 3.20)
+      # project(MyProject)
+      # Previously had: set(CMAKE_GENERATOR_TOOLSET "v142")
+      # Remove or update to:
+      # set(CMAKE_GENERATOR_TOOLSET "v143")  # or omit to use default
+  - language: yaml
+    label: "Option B: pin to windows-2022 to keep v142 support"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2022   # has both v142 and v143 available
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build with CMake
+              run: cmake -B build -T v142 && cmake --build build
+  - language: yaml
+    label: "Option C: install VS 2019 build tools on windows-latest (slow)"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install VS 2019 Build Tools
+              run: |
+                choco install visualstudio2019buildtools --package-parameters "--add Microsoft.VisualStudio.Component.VC.v142.x86.x64" -y
+prevention:
+  - "Audit all .vcxproj and CMakeLists.txt files for explicit v142 toolset references before migrating to windows-latest"
+  - "Pin to `windows-2022` in CI to preserve VS 2019 toolchain availability while planning an upgrade"
+  - "Watch https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md for current pre-installed toolchain versions"
+  - "Use `vswhere` in a pre-build step to detect installed VS components and fail fast with a descriptive error"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/10751"
+    label: "runner-images #10751 — windows-latest migration to Windows Server 2025"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md"
+    label: "Windows Server 2025 runner image README — pre-installed software"
+  - url: "https://learn.microsoft.com/en-us/cpp/build/cmake-presets-vs?view=msvc-170"
+    label: "Microsoft Docs — CMake toolset configuration"

package/errors/runner-environment/setup-go-eol-version-not-in-tool-cache.yml

@@ -0,0 +1,78 @@
+id: runner-environment-173
+title: 'actions/setup-go with EOL Go versions (1.21, 1.22) not in runner tool cache — slow downloads or failures'
+category: runner-environment
+severity: warning
+tags:
+  - setup-go
+  - go
+  - golang
+  - eol
+  - tool-cache
+  - go-version
+patterns:
+  - regex: 'go version [\d.]+ is not in the tool-cache.*Falling back to download|go\d+\.\d+\.?\d*.*not found.*tool.cache'
+    flags: 'i'
+  - regex: 'Downloading go[\d.]+.*from https://dl\.google\.com/go'
+    flags: 'i'
+  - regex: 'Failed to download Go from|Unable to find Go version.*in cache'
+    flags: 'i'
+error_messages:
+  - "go version 1.21.x is not in the tool-cache. Falling back to downloading from https://dl.google.com/go"
+  - "go version 1.22.x is not in the tool-cache. Falling back to downloading from https://dl.google.com/go"
+  - "Failed to download Go from https://dl.google.com/go"
+  - "Unable to find Go version 1.21 in cache"
+root_cause: |
+  GitHub removes end-of-life Go versions from the runner image tool cache after their
+  official support window closes. Go follows a two-release support policy: only the two
+  most recent major releases receive security updates. Once a version is EOL, it is no
+  longer pre-installed on new runner images.
+
+  Affected versions as of 2025-2026:
+  - Go 1.21 — EOL February 6, 2024 (removed from runner tool cache ~Q2 2024)
+  - Go 1.22 — EOL August 6, 2025 (removed from runner tool cache ~Q4 2025)
+
+  When actions/setup-go requests a version not in the tool cache, it falls back to
+  downloading the Go toolchain from dl.google.com/go. This fallback:
+  1. Adds 30-90 seconds of download time per job (depending on network speed)
+  2. Fails entirely in self-hosted runners without internet access or strict outbound
+     firewall rules blocking dl.google.com
+  3. May fail intermittently if the Google CDN experiences transient issues
+
+  Workflows with many parallel matrix jobs (e.g., matrix of Go versions or OS targets)
+  multiply this overhead: 20 parallel jobs each downloading Go = 20 concurrent CDN requests.
+fix: |
+  Upgrade to a currently-supported Go version. As of 2025-2026, the two supported releases
+  are Go 1.23 and Go 1.24. Both are pre-cached in the runner tool cache and resolve
+  instantly without any network download.
+
+  Use the go-version-file input to read the version from go.mod, ensuring your CI always
+  matches your project's declared Go version.
+fix_code:
+  - language: yaml
+    label: 'Pin to a supported Go version (no tool-cache miss)'
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'   # or '1.23' — both are in the runner tool cache
+          cache: true
+  - language: yaml
+    label: 'Use go-version-file to read version from go.mod'
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'  # reads `go 1.24` directive from go.mod
+          cache: true
+prevention:
+  - 'Keep go-version in your workflows aligned with the go directive in go.mod'
+  - 'Upgrade Go versions proactively before EOL — the Go team announces EOL dates 6 months in advance'
+  - 'Use go-version-file: go.mod so your CI automatically follows your module declaration'
+  - 'Monitor https://go.dev/doc/devel/release for maintenance status of Go releases'
+docs:
+  - url: 'https://go.dev/doc/devel/release'
+    label: 'Go release history and maintenance policy'
+  - url: 'https://github.com/actions/setup-go'
+    label: 'actions/setup-go — go-version and go-version-file inputs'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'GitHub runner images — preinstalled tool versions'

package/errors/silent-failures/silent-failures-091.yml

@@ -0,0 +1,94 @@
+id: silent-failures-091
+title: '`github.ref_name` Returns Ephemeral Merge Ref (`123/merge`) on `pull_request` Trigger, Not Branch Name'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - ref-name
+  - pull-request
+  - docker
+  - branch-name
+  - deployment
+patterns:
+  - regex: '\d+/merge'
+    flags: 'i'
+error_messages:
+  - "invalid reference format"
+  - "invalid tag format"
+root_cause: |
+  When a workflow is triggered by a `pull_request` event, GitHub creates an ephemeral
+  merge commit that merges the PR head into the base branch. The context variables for
+  this run reflect the merge ref, not the source branch:
+
+  - `github.ref` = `refs/pull/123/merge`
+  - `github.ref_name` = `123/merge`
+  - `github.sha` = SHA of the ephemeral merge commit
+  - `github.head_ref` = `feature-branch-name` (the actual PR branch)
+  - `github.base_ref` = `main` (the target branch)
+
+  Using `github.ref_name` in contexts that expect a branch name silently produces
+  the merge ref string `123/merge` instead:
+
+  - **Docker image tags**: `docker.io/myapp:123/merge` — Docker rejects the forward slash
+    as an invalid tag character (`invalid reference format` error), OR worse, interprets
+    `123` as a registry name.
+  - **Deployment environment names**: The environment is created as `123/merge` rather
+    than the branch name, causing routing rules to miss the deployment.
+  - **Branch-based conditional logic**: `if: github.ref_name == 'feature-foo'` always
+    evaluates to false on pull_request events.
+  - **Artifact naming**: Artifacts uploaded with the ref_name contain forward slashes,
+    causing path traversal issues on some download handlers.
+
+  `github.head_ref` is only populated for `pull_request` and `pull_request_target`
+  events, making branch detection logic that works on push but silently fails on PR
+  events harder to diagnose.
+fix: |
+  Use the correct context variable for each event type:
+
+  - For the PR's source branch name: `github.head_ref` (only set on pull_request events)
+  - For push events' branch name: `github.ref_name`
+  - For a branch name that works across both event types, use a conditional expression.
+fix_code:
+  - language: yaml
+    label: "Unified branch name across push and pull_request events"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Determine branch name
+              id: branch
+              run: |
+                if [ "${{ github.event_name }}" = "pull_request" ]; then
+                  echo "name=${{ github.head_ref }}" >> "$GITHUB_OUTPUT"
+                else
+                  echo "name=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+                fi
+
+            - name: Build and tag Docker image
+              run: |
+                # Sanitize slashes for use in image tags
+                TAG=$(echo "${{ steps.branch.outputs.name }}" | tr '/' '-')
+                docker build -t "myapp:${TAG}" .
+  - language: yaml
+    label: "Expression-based branch name (no shell step needed)"
+    code: |
+      env:
+        BRANCH_NAME: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+          steps:
+            - run: echo "Deploying branch ${{ env.BRANCH_NAME }}"
+prevention:
+  - "Never use `github.ref_name` directly in Docker image tags — always sanitize forward slashes with `tr '/' '-'` or similar"
+  - "Test branch-detection expressions with both `push` and `pull_request` triggers in a dry-run workflow"
+  - "Use `github.head_ref` for PR branch name and `github.ref_name` for push branch name — they are NOT interchangeable"
+  - "Add an explicit check: if `github.ref_name` contains a `/`, the workflow is running on a pull_request or merge ref, not a regular branch"
+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 Docs — github context reference"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request"
+    label: "GitHub Docs — pull_request event"

package/errors/triggers/triggers-067.yml

@@ -0,0 +1,134 @@
+id: triggers-067
+title: 'workflow_run types:[completed] fires prematurely with conclusion:null before referenced workflow finishes'
+category: triggers
+severity: error
+tags:
+  - workflow_run
+  - conclusion
+  - null
+  - premature-trigger
+  - race-condition
+  - completed
+patterns:
+  - regex: 'workflow_run\.conclusion.*null'
+    flags: 'i'
+  - regex: 'github\.event\.workflow_run\.conclusion'
+    flags: 'i'
+  - regex: 'conclusion.*randomly.*fail'
+    flags: 'i'
+error_messages:
+  - "github.event.workflow_run.conclusion returned null — job skipped unexpectedly"
+  - "Unable to extend GITHUB_TOKEN expiration time due to: GITHUB_TOKEN has expired."
+root_cause: |
+  The `workflow_run` event with `types: [completed]` is documented to fire only after the
+  referenced workflow finishes running. However, a known race condition in GitHub Actions'
+  event delivery (tracked in actions/runner#4035) causes the event to fire a second time
+  BEFORE the workflow has fully completed — specifically before GitHub has written the final
+  `conclusion` value to the workflow run record.
+
+  When this premature trigger fires, `github.event.workflow_run.conclusion` evaluates to
+  `null` (or an empty string `""`). Any job guarded with:
+
+    if: github.event.workflow_run.conclusion == 'success'
+
+  will evaluate to `false` and be skipped, producing a confusing pattern where the
+  downstream workflow runs twice — once skipped, once (correctly) executed.
+
+  GitHub Support confirmed this as a platform-side delay: the `conclusion` field remains
+  `null` while GitHub's backend is still updating the workflow run record. The event
+  is dispatched before the record is fully consistent.
+
+  This affects all workflows that use `on.workflow_run` with `types: [completed]` and
+  check `github.event.workflow_run.conclusion` to gate job execution.
+fix: |
+  Two mitigations are available:
+
+  1. **Guard with `conclusion != ''`** — Add a condition that explicitly rejects null/empty
+     `conclusion` values before checking for `'success'`:
+
+     if: >-
+       github.event.workflow_run.conclusion != '' &&
+       github.event.workflow_run.conclusion == 'success'
+
+  2. **Re-query via REST API** — Instead of trusting `github.event.workflow_run.conclusion`,
+     use the Actions REST API to fetch the current workflow run conclusion at step runtime:
+
+     gh api /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }} \
+       --jq '.conclusion'
+
+     This always returns the up-to-date value, bypassing the event payload race condition.
+
+  Note: adding a `sleep` between trigger and conclusion check is NOT a reliable fix, as
+  the delay between trigger and backend consistency is variable and can exceed seconds.
+fix_code:
+  - language: yaml
+    label: 'Problem: conclusion check fails on premature null trigger'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI Build']
+          types: [completed]
+
+      jobs:
+        deploy:
+          # This randomly evaluates to false when conclusion is null
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+  - language: yaml
+    label: 'Fix: guard against null conclusion before equality check'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI Build']
+          types: [completed]
+
+      jobs:
+        deploy:
+          # Explicitly reject null/empty conclusion to avoid premature-trigger skips
+          if: >-
+            github.event.workflow_run.conclusion != '' &&
+            github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+  - language: yaml
+    label: 'Fix: re-query conclusion via REST API for reliable value'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI Build']
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check conclusion via API
+              id: check
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                conclusion=$(gh api \
+                  /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }} \
+                  --jq '.conclusion')
+                echo "conclusion=$conclusion" >> "$GITHUB_OUTPUT"
+
+            - name: Deploy
+              if: steps.check.outputs.conclusion == 'success'
+              run: echo "Deploying..."
+prevention:
+  - "Never rely solely on `github.event.workflow_run.conclusion == 'success'` without a null guard."
+  - "Add `github.event.workflow_run.conclusion != ''` as an explicit first condition to reject premature triggers."
+  - "If downstream jobs must be fully reliable, re-query conclusion via the REST API rather than reading from the event payload."
+  - "Monitor the Actions tab for unexpectedly skipped `workflow_run` triggered runs — they indicate premature triggers."
+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 event'
+  - url: 'https://github.com/actions/runner/issues/4035'
+    label: 'actions/runner#4035: workflow_run triggers before referenced workflow completes'
+  - url: 'https://stackoverflow.com/questions/73107307/any-workaround-for-github-actions-workflow-run-conclusion-randomly-failing'
+    label: 'Stack Overflow: workflow_run.conclusion randomly failing'
+  - url: 'https://github.com/orgs/community/discussions/58929'
+    label: 'GitHub Community #58929: github.event.workflow_run.conclusion is always null'

package/errors/yaml-syntax/env-context-unavailable-defaults-run-working-directory.yml

@@ -0,0 +1,113 @@
+id: yaml-syntax-065
+title: 'env context unavailable in defaults.run.working-directory — "Unrecognized named-value: env"'
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - context
+  - defaults
+  - working-directory
+  - expression
+  - context-availability
+patterns:
+  - regex: 'Unrecognized named-value: ''env''.*defaults|defaults.*working.directory.*env'
+    flags: 'i'
+  - regex: 'The workflow is not valid.*defaults\.run\.working-directory.*env\.'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: ''env''.*position.*working.directory'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/<workflow>.yml (Line: X, Col: Y): Unrecognized named-value: 'env'. Located at position 1 within expression: env.WORKING_DIR"
+  - "Unrecognized named-value: 'env'"
+root_cause: |
+  The `env` context is only available during step execution — not at job evaluation time.
+  `defaults.run.working-directory` is a job-level field evaluated before any steps run,
+  so GitHub Actions rejects references to `env.*` inside it with "Unrecognized named-value: 'env'".
+
+  This is the same fundamental limitation that affects other job-level fields (if:,
+  runs-on, timeout-minutes, continue-on-error) but is less documented for defaults.run.
+
+  Common patterns that fail:
+  - Setting a shared working directory from a workflow-level env variable:
+      env:
+        APP_DIR: './packages/app'
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.APP_DIR }}  # FAILS — env not available here
+
+  - Reading an env var set in another job:
+      jobs:
+        setup:
+          ...
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.BUILD_DIR }}  # FAILS — env from another job not visible
+
+  The limitation applies to all expressions in defaults.run.working-directory and
+  defaults.run.shell at both the workflow level and the job level.
+fix: |
+  Replace env context references in defaults.run.working-directory with contexts that are
+  available at job evaluation time:
+
+  1. Use vars.* (repository or environment variables configured in Settings) for static paths
+  2. Use inputs.* if inside a reusable workflow called with workflow_call
+  3. Set working-directory on each individual step instead of at defaults level
+  4. Use an outputs chain from a prior job if the path is computed dynamically
+fix_code:
+  - language: yaml
+    label: 'WRONG — env context in defaults.run.working-directory (fails)'
+    code: |
+      env:
+        APP_DIR: './packages/app'
+
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.APP_DIR }}  # Error: Unrecognized named-value 'env'
+  - language: yaml
+    label: 'FIX option 1 — use vars context (repository variable)'
+    code: |
+      # Configure APP_DIR in Settings > Secrets and variables > Variables
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ vars.APP_DIR }}  # repository variable — available at job level
+  - language: yaml
+    label: 'FIX option 2 — set working-directory on each step directly'
+    code: |
+      jobs:
+        build:
+          env:
+            APP_DIR: './packages/app'
+          steps:
+            - name: Build
+              run: npm run build
+              working-directory: ${{ env.APP_DIR }}  # env IS available at step level
+            - name: Test
+              run: npm test
+              working-directory: ${{ env.APP_DIR }}
+  - language: yaml
+    label: 'FIX option 3 — hardcode the path in defaults.run'
+    code: |
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ./packages/app  # literal path, no context expression needed
+prevention:
+  - 'Only use vars.*, github.*, inputs.*, or needs.*.outputs.* in job-level expressions — env.* is never available at job level'
+  - 'For shared working directories, prefer literal paths in defaults.run.working-directory over expressions'
+  - 'If the path must be dynamic, use step-level working-directory instead of defaults.run'
+  - 'Use actionlint to validate workflows locally — it catches env context misuse in job-level fields'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-default-values-for-jobs'
+    label: 'GitHub Actions — Setting default values for jobs (defaults.run)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Actions context availability by workflow key'
+  - url: 'https://github.com/rhysd/actionlint'
+    label: 'actionlint — static checker that validates context availability'

package/errors/yaml-syntax/yaml-syntax-064.yml

@@ -0,0 +1,119 @@
+id: yaml-syntax-064
+title: 'strategy.matrix.include/exclude entry value specified as array causes "A sequence was not expected"'
+category: yaml-syntax
+severity: error
+tags:
+  - matrix
+  - include
+  - exclude
+  - array-value
+  - sequence
+  - validation-error
+  - strategy
+patterns:
+  - regex: 'A sequence was not expected'
+    flags: 'i'
+  - regex: 'matrix\.(include|exclude).*\[.*\]'
+    flags: 'i'
+  - regex: 'strategy.*matrix.*include.*sequence'
+    flags: 'i'
+error_messages:
+  - "Error: The template is not valid. .github/workflows/workflow.yml (Line: 12, Col: 18): A sequence was not expected"
+  - "A sequence was not expected"
+root_cause: |
+  In a `strategy.matrix`, the top-level matrix dimensions accept arrays of scalars:
+
+    php: ['8.2', '8.3', '8.4']   # valid — array of scalars
+
+  However, inside `include:` and `exclude:` entries, ALL values must be scalars
+  (string, number, boolean). Arrays are not allowed:
+
+    include:
+      - os: ubuntu-latest
+        php: ['8.2']              # INVALID — array not allowed in include/exclude entries
+
+  This is a common mistake when a developer copies the variable name from the main
+  matrix definition (where it IS an array) and pastes it into an `include:` or
+  `exclude:` entry without unwrapping it.
+
+  GitHub Actions' expression evaluator validates the template before execution and
+  throws an immediate hard failure:
+
+    Error: The template is not valid. .github/workflows/X.yml (Line: N, Col: M):
+    A sequence was not expected
+
+  The error points to the line where the array value starts (the `[` character),
+  which can be confusing because arrays are valid YAML and valid in other matrix
+  contexts. The fix is simply to remove the brackets and use a scalar value.
+
+  Tracked in rhysd/actionlint#630 (actionlint static analysis issue requesting
+  detection of this pattern).
+fix: |
+  Replace any array-valued entries inside `include:` or `exclude:` with scalar values.
+  Each `include:`/`exclude:` entry is a single-combination filter — it selects or adds
+  one specific combination, so the value must be a scalar that matches exactly one item.
+
+  If you need to include multiple values for a key, write separate `include:` entries,
+  one per value.
+fix_code:
+  - language: yaml
+    label: 'Problem: array value inside include entry — triggers "A sequence was not expected"'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest]
+          php: ['8.3', '8.4', '8.5']
+
+          include:
+            # ERROR: php value is an array — not allowed inside include entries
+            - os: ubuntu-latest
+              php: ['8.2']      # ← "A sequence was not expected" on this line
+
+          exclude:
+            # ERROR: os value is an array — not allowed inside exclude entries
+            - os: [macos-latest]
+              php: '8.3'        # ← "A sequence was not expected"
+  - language: yaml
+    label: 'Fix: use scalar values inside include/exclude entries'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest]
+          php: ['8.3', '8.4', '8.5']
+
+          include:
+            # CORRECT: scalar value — adds ubuntu-latest × 8.2 as an extra job
+            - os: ubuntu-latest
+              php: '8.2'        # ← scalar, not array
+
+          exclude:
+            # CORRECT: scalar value — excludes macos-latest × 8.3 combination
+            - os: macos-latest
+              php: '8.3'        # ← scalar, not array
+  - language: yaml
+    label: 'Multiple include entries for multiple specific combinations'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest]
+          node: [18, 20]
+
+          include:
+            # To include multiple specific combinations, write separate entries:
+            - os: ubuntu-latest
+              node: 22          # one entry per extra combination
+            - os: ubuntu-latest
+              node: 23          # another entry for a different combination
+            # NOT: node: [22, 23]  ← this would fail with "A sequence was not expected"
+prevention:
+  - "Values inside `include:` and `exclude:` entries must be scalars — never use array syntax `[...]` there."
+  - "When copying matrix variable names from the top-level dimensions to include/exclude entries, remove the brackets."
+  - "Use actionlint (github.com/rhysd/actionlint) to statically validate your workflow files before pushing."
+  - "If you need multiple combinations, write multiple separate `include:` entries instead of one entry with an array value."
+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'
+  - url: 'https://github.com/rhysd/actionlint/issues/630'
+    label: 'rhysd/actionlint#630: Detect array values in matrix include/exclude entries'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrixinclude'
+    label: 'GitHub Docs: jobs.<job_id>.strategy.matrix.include syntax reference'

package/package.json

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