@htekdev/actions-debugger 1.0.130 → 1.0.132

package/errors/concurrency-timing/concurrency-timing-061.yml

@@ -0,0 +1,138 @@
+id: concurrency-timing-061
+title: '`github.workflow` in reusable workflow (`workflow_call`) returns caller''s name — shared concurrency group causes deadlock'
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - reusable-workflow
+  - workflow-call
+  - github-workflow-context
+  - deadlock
+  - concurrency-group
+patterns:
+  - regex: 'Canceling since a deadlock for concurrency group .+ was detected between .+ and .+'
+    flags: 'i'
+  - regex: 'deadlock.*concurrency group.*detected'
+    flags: 'i'
+error_messages:
+  - "Canceling since a deadlock for concurrency group 'CI-refs/heads/main' was detected between 'CI workflow' and 'deploy'"
+  - "Canceling since a deadlock for concurrency group 'test-refs/heads/master' was detected between 'test workflow' and 'deploy'"
+root_cause: |
+  When a caller workflow invokes a reusable workflow via `uses:` (the `workflow_call` trigger),
+  the `github.workflow` context variable inside the CALLEE resolves to the CALLER's workflow
+  name — not the callee's own filename. This is documented behavior but it directly undermines
+  the widely recommended concurrency group pattern of `${{ github.workflow }}-${{ github.ref }}`.
+
+  If both the caller and the callee define:
+  ```yaml
+  concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+  ```
+
+  Both workflows compute the SAME group key (because `github.workflow` is the caller's name in
+  both). GitHub detects that two workflow instances are competing for the same concurrency slot
+  in a way that cannot resolve — one is waiting for the other which is waiting for the first —
+  treats it as a deadlock, and cancels one of the runs.
+
+  **Why this is especially confusing:**
+  The fix recommended for general concurrency group collisions (`${{ github.workflow }}-${{ github.ref }}`)
+  is itself the cause of this deadlock when applied naively to reusable workflows. Teams that
+  copy the "safe" concurrency pattern from caller to callee introduce the bug.
+
+  **Real-world evidence:**
+  - actions/runner#3205: `github.workflow` returns parent workflow name in child workflows
+  - vergil-project/vergil-actions#176: ci-push.yml calls ci.yml via workflow_call; both use
+    `${{ github.workflow }}-${{ github.ref }}`; deadlock detected on every push
+  - github/gh-aw#35173: workflow_call fan-out cancellations due to shared concurrency namespace
+  - SO #78101326 (6 upvotes, 1738 views): "GitHub Actions concurrency deadlock" — 6 answers
+    confirming the root cause is `github.workflow` returning the caller name
+fix: |
+  Use `github.workflow_ref` instead of `github.workflow` in the CALLEE (reusable) workflow.
+  `github.workflow_ref` contains the full workflow file path (e.g.
+  `.github/workflows/deploy.yml@refs/heads/main`), which is unique per callee file and
+  does NOT inherit the caller's name.
+
+  **Preferred approach:** Define concurrency ONLY in the caller workflow and remove it from the
+  callee entirely. The callee runs as part of the caller's run and does not need its own
+  concurrency group. This is the cleanest fix and matches GitHub's recommendations for
+  reusable workflow design.
+
+  **Avoid:** Defining concurrency in both caller and callee with the same expression — this
+  is the root cause of the deadlock regardless of which context variable is used for the group
+  key, unless the keys are guaranteed to differ.
+fix_code:
+  - language: yaml
+    label: 'Callee (reusable workflow): use github.workflow_ref — unique per callee file'
+    code: |
+      # .github/workflows/deploy.yml (callee — reusable workflow)
+      name: Deploy
+
+      on:
+        workflow_call:
+
+      # ✅ github.workflow_ref includes the full path, NOT the caller's name
+      concurrency:
+        group: ${{ github.workflow_ref }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Preferred: define concurrency only in the caller, none in the callee'
+    code: |
+      # .github/workflows/ci.yml (caller workflow)
+      name: CI
+
+      on:
+        push:
+          branches: [main]
+
+      # Concurrency defined only in the caller
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          # ✅ No concurrency block here — the reusable workflow has no concurrency group
+          uses: ./.github/workflows/deploy.yml
+
+      ---
+      # .github/workflows/deploy.yml (callee — reusable workflow)
+      name: Deploy
+
+      on:
+        workflow_call:
+
+      # ✅ No concurrency block — inherit scheduling from caller
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+prevention:
+  - "Never use `github.workflow` in a reusable workflow's concurrency group — it resolves to the caller's name, not the callee's"
+  - "Use `github.workflow_ref` in callee workflows if a concurrency group is truly needed there"
+  - "Prefer defining concurrency only in the caller when calling reusable workflows via `uses:` — keep callee stateless"
+  - "Audit all reusable workflows for concurrency groups that use `github.workflow` and replace with `github.workflow_ref`"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Control the concurrency of workflows and jobs'
+  - 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 — github.workflow_ref field'
+  - url: 'https://github.com/actions/runner/issues/3205'
+    label: 'actions/runner#3205: github.workflow returns parent name in child workflows (closed not_planned)'
+  - url: 'https://stackoverflow.com/questions/78101326/github-actions-concurrency-deadlock'
+    label: 'SO #78101326: GitHub Actions concurrency deadlock in reusable workflows (6 upvotes, 1738 views)'

package/errors/known-unsolved/known-unsolved-076.yml

@@ -0,0 +1,142 @@
+id: known-unsolved-076
+title: '`env` context unavailable in `strategy.matrix` — workflow env vars cannot be used in matrix definitions'
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - env-context
+  - strategy
+  - fromJSON
+  - dynamic-matrix
+  - context-availability
+  - known-limitation
+patterns:
+  - regex: 'Error when evaluating .+strategy.+ for job'
+    flags: 'i'
+  - regex: 'strategy.*matrix.*\$\{\{.*env\.'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: .+env.+ \(Line: \d+'
+    flags: 'i'
+error_messages:
+  - "Error when evaluating 'strategy' for job 'build'. .github/workflows/deploy.yaml (Line: 10, Col: 15): Error parsing fromJson"
+  - "Error when evaluating 'strategy' for job 'test'. Input string '3.11' is not a valid number. Path '[0]'"
+  - "Error when evaluating 'strategy' for job 'matrix-job': Object reference not set to an instance of an object"
+root_cause: |
+  The `env` context — workflow-level environment variables defined under the top-level `env:` key
+  — is NOT available during evaluation of `strategy.matrix`. GitHub Actions evaluates the
+  `strategy:` block at workflow QUEUING time, before jobs are dispatched and before environment
+  variable interpolation occurs. Any expression like `${{ env.VERSIONS_JSON }}` or
+  `${{ fromJSON(env.VERSIONS_JSON) }}` inside `strategy.matrix` resolves to an empty string
+  or produces a parse error.
+
+  **GitHub's documented context availability:**
+  Per the official context availability table, `env` is explicitly NOT listed as available in
+  `jobs.<job_id>.strategy`. Available contexts there are only: `github`, `inputs`, `vars`,
+  `needs`, `strategy`, and `matrix`.
+
+  **Common failure patterns:**
+  - Using `${{ fromJSON(env.MY_VERSIONS) }}` to share a JSON array between matrix and other steps
+  - Setting `env: DEPLOY_ENVS: '["staging","production"]'` at workflow level and referencing it
+    in the matrix include/exclude blocks
+  - Using workflow-level env vars to DRY up matrix configs shared with `run:` script logic
+
+  **Why this surprises developers:**
+  - `env` IS available inside `jobs.<job_id>.steps.*` — the limitation is specific to `strategy`
+  - The error message "Error parsing fromJson" doesn't mention that `env` context is unavailable
+  - The empty-string resolution (when no parse error) causes a silent empty matrix, not an error
+
+  Sources: actions/runner#480 (281 👍, open since 2020 — most-upvoted env context limitation);
+  SO#74072206 (10 upvotes, 19,053 views); SO#76039616 (6 upvotes, 10,482 views)
+fix: |
+  Three workarounds exist, in order of preference:
+
+  **Option 1 — Use `vars` context (org/repo-level variables)**
+  Org-level and repo-level variables (`vars.*`) ARE available in `strategy.matrix`.
+  Move shared values to repository Settings → Secrets and variables → Variables instead of
+  workflow-level `env:`.
+
+  **Option 2 — Compute matrix in a previous job's output (most flexible)**
+  Use a dedicated setup job that outputs the matrix JSON, then reference it in dependent
+  jobs via `fromJSON(needs.setup.outputs.matrix)`. This also enables dynamic matrix
+  generation from files, APIs, or scripts.
+
+  **Option 3 — Hardcode values directly in strategy.matrix**
+  Duplicate the values in `strategy.matrix` explicitly. Avoids the DRY violation but
+  is the simplest fix when values rarely change.
+fix_code:
+  - language: yaml
+    label: 'Option 1: Use vars context — repo/org variables ARE available in strategy'
+    code: |
+      # In repo Settings → Secrets and variables → Variables, create:
+      # Name: PYTHON_VERSIONS  Value: ["3.10","3.11","3.12"]
+
+      jobs:
+        test:
+          strategy:
+            matrix:
+              # ✅ vars context IS available in strategy.matrix
+              python-version: ${{ fromJSON(vars.PYTHON_VERSIONS) }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: python -m pytest
+  - language: yaml
+    label: 'Option 2: Compute matrix in a setup job, pass via needs outputs'
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.set-matrix.outputs.matrix }}
+          steps:
+            - id: set-matrix
+              run: |
+                # Build matrix from any source: env var, file, API, conditional logic
+                echo 'matrix={"python-version":["3.10","3.11","3.12"]}' >> "$GITHUB_OUTPUT"
+
+        test:
+          needs: setup
+          strategy:
+            matrix:
+              # ✅ fromJSON(needs.*.outputs.*) IS available in strategy.matrix
+              ${{ fromJSON(needs.setup.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: python -m pytest
+  - language: yaml
+    label: 'Anti-pattern: env context in strategy.matrix causes parse error'
+    code: |
+      # ❌ Workflow-level env vars are NOT available in strategy.matrix
+
+      env:
+        PYTHON_VERSIONS: '["3.10","3.11","3.12"]'
+
+      jobs:
+        test:
+          strategy:
+            matrix:
+              # This causes: "Error when evaluating 'strategy' for job 'test'"
+              python-version: ${{ fromJSON(env.PYTHON_VERSIONS) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: python --version
+prevention:
+  - "Use `vars.*` (repo/org variables from Settings) instead of workflow `env:` for values shared between matrix and steps"
+  - "Generate dynamic matrices in a dedicated setup job and pass via `needs.*.outputs.*`"
+  - "Consult the GitHub Actions context availability table before using any context in `strategy` — not all contexts are available there"
+  - "actionlint will flag `env` context usage in strategy blocks — add it to your CI pipeline or pre-commit hooks"
+  - "Remember: `env` IS available in `steps.*.run`, `steps.*.with`, and most other places — the restriction is specific to `strategy` and `concurrency`"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability'
+    label: 'GitHub Docs: Context availability table (env not listed for strategy)'
+  - url: 'https://github.com/actions/runner/issues/480'
+    label: 'actions/runner#480: Workflow level env does not work in all fields (281 upvotes, open since 2020)'
+  - url: 'https://stackoverflow.com/questions/74072206/github-actions-use-variables-in-matrix-definition'
+    label: 'SO #74072206: Use variables in matrix definition (10 upvotes, 19,053 views)'
+  - url: 'https://stackoverflow.com/questions/76039616/how-to-read-in-an-array-of-strings-to-matrix-in-github-actions'
+    label: 'SO #76039616: Read array of strings into matrix (6 upvotes, 10,482 views)'

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

@@ -0,0 +1,158 @@
+id: permissions-auth-076
+title: '`docker push` to ghcr.io fails with 403 / "denied: permission_denied: write_package" — missing `packages: write` permission'
+category: permissions-auth
+severity: error
+tags:
+  - ghcr
+  - github-packages
+  - container-registry
+  - packages-write
+  - github-token
+  - docker-push
+  - 403
+  - permission-denied
+patterns:
+  - regex: 'denied: permission_denied: write_package'
+    flags: 'i'
+  - regex: 'Error response from daemon.*denied.*ghcr\.io.*403'
+    flags: 'i'
+  - regex: 'error parsing HTTP 403 response body.*ghcr\.io'
+    flags: 'i'
+  - regex: 'unauthorized.*ghcr\.io.*write'
+    flags: 'i'
+  - regex: 'The token provided does not match expected format for.*packages'
+    flags: 'i'
+error_messages:
+  - "Error response from daemon: denied: permission_denied: write_package"
+  - "error parsing HTTP 403 response body: unexpected end of JSON input: \"\""
+  - "denied: denied"
+  - "unauthorized: authentication required"
+  - "buildx failed with: ERROR [auth] ghcr.io token refreshing failed with status: 403 Forbidden"
+root_cause: |
+  GitHub Container Registry (ghcr.io) requires the `packages: write` permission
+  to be explicitly granted in the workflow job's `permissions:` block before
+  `GITHUB_TOKEN` can push (publish) images.
+
+  Since GitHub tightened default GITHUB_TOKEN permissions in 2023, new repositories
+  and organization workflows that set "Restrict GitHub Actions permissions" to
+  "Read repository contents and packages" have `packages: write` DISABLED by default.
+  Without this permission, any `docker push` or `docker buildx build --push` to
+  `ghcr.io` fails with a 403 at the registry level.
+
+  **Why this is confusing:**
+  - `docker login ghcr.io -u ${{ github.actor }} -p ${{ secrets.GITHUB_TOKEN }}`
+    SUCCEEDS (read/login is allowed) — the login step passes
+  - The failure occurs on `docker push`, not login
+  - The error message "denied: permission_denied: write_package" or the generic 403
+    does not directly mention the `packages: write` permission or how to add it
+  - The same workflow may work on repositories created before the permission
+    tightening (where `packages: write` was still the default)
+
+  **Additional requirement — linking the package to the repository:**
+  On first publish, the package is created as unlinked. If the workflow runs in a
+  fork or if the package visibility is set to Private with no repository link, the
+  GITHUB_TOKEN push will also fail even with `packages: write`. The package must be
+  linked to the source repository for GITHUB_TOKEN to authenticate.
+
+  Source: SO #70646920 (22 upvotes, 34k views), SO #78342148, GitHub Docs on
+  container registry permissions.
+fix: |
+  Add `packages: write` to the job's `permissions:` block. This is the most common
+  fix and resolves the majority of GHCR push 403 errors:
+
+  ```yaml
+  jobs:
+    build-and-push:
+      runs-on: ubuntu-latest
+      permissions:
+        contents: read
+        packages: write   # Required to push to ghcr.io
+  ```
+
+  **If login succeeds but push still fails:**
+  1. Verify the package is linked to the repository: go to the package on
+     `github.com/{owner}/{package}` → Package settings → "Add Repository"
+  2. Ensure the package visibility matches the repository (private repo → private
+     package, or set the package to public)
+  3. For organization repositories, confirm the organization has not blocked
+     GitHub Actions from creating packages (Org Settings → Actions → General)
+
+  **If using a separate PAT or App token:**
+  GITHUB_TOKEN with `packages: write` is sufficient for pushing to packages owned
+  by the same repository. For cross-repository or org-level package publishing,
+  use a Fine-Grained PAT with "Packages: Read and write" scope or a GitHub App
+  with "Packages: write" permission.
+fix_code:
+  - language: yaml
+    label: 'Correct job-level permissions for docker push to ghcr.io'
+    code: |
+      name: Build and Push Docker Image
+      on:
+        push:
+          branches: [main]
+      jobs:
+        build-push:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            packages: write   # <-- Required for ghcr.io push
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Log in to GitHub Container Registry
+              uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Build and push
+              uses: docker/build-push-action@v6
+              with:
+                context: .
+                push: true
+                tags: ghcr.io/${{ github.repository }}:latest
+  - language: yaml
+    label: 'Workflow-level permissions fallback (if setting per-job is not possible)'
+    code: |
+      name: Build and Push Docker Image
+      on:
+        push:
+          branches: [main]
+
+      # Set at workflow level — applies to ALL jobs
+      permissions:
+        contents: read
+        packages: write
+
+      jobs:
+        build-push:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Log in to ghcr.io
+              uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+            - name: Push image
+              run: |
+                docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
+                docker push ghcr.io/${{ github.repository }}:${{ github.sha }}
+prevention:
+  - "Always add `packages: write` to the job permissions block for any job that pushes images to ghcr.io"
+  - "Note that docker login to ghcr.io succeeds without packages:write — always test the actual push step to validate permissions"
+  - "Check your organization's Actions general settings for any policies that restrict packages creation"
+  - "When using docker/build-push-action with push: true, the packages: write permission is required on the job"
+  - "For fork PRs, packages: write is unavailable — use conditional steps: `if: github.event.pull_request.head.repo.full_name == github.repository`"
+  - "Link the package to its source repository after first creation to enable GITHUB_TOKEN-based pushes in future runs"
+docs:
+  - url: 'https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry'
+    label: 'GitHub Docs: Working with the Container registry (ghcr.io)'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Docs: GITHUB_TOKEN permissions reference'
+  - url: 'https://stackoverflow.com/questions/70646920/github-token-permission-denied-write-package-when-build-and-push-docker-in-githu'
+    label: 'SO #70646920: GITHUB_TOKEN permission denied write_package (22 upvotes, 34k views)'
+  - url: 'https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility'
+    label: 'GitHub Docs: Configuring a package access control and visibility'

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

@@ -0,0 +1,160 @@
+id: runner-environment-245
+title: 'ARC ephemeral runner pod hangs indefinitely after workflow job cancellation — "Skipping message Job. Job message not found ... job was canceled"'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - kubernetes
+  - ephemeral-runner
+  - cancellation
+  - stuck-runner
+  - gha-runner-scale-set
+  - job-canceled
+patterns:
+  - regex: 'Skipping message Job\. Job message not found .+ job was canceled'
+    flags: 'i'
+  - regex: 'EphemeralRunner.*status.*Running.*canceled'
+    flags: 'i'
+  - regex: 'Registration .+ was not found\.'
+    flags: 'i'
+  - regex: 'POST request to .+acquirejob failed\. HTTP Status: Conflict'
+    flags: 'i'
+error_messages:
+  - "Skipping message Job. Job message not found 'e420db7b-c780-5ae4-8145-4eea09b87aea'. job was canceled"
+  - "POST request to https://run-actions-*.actions.githubusercontent.com/*/acquirejob failed. HTTP Status: Conflict"
+  - "Registration 470d6c87-f8c4-411f-87d0-6b069233ccc7 was not found."
+root_cause: |
+  When a GitHub Actions workflow job is canceled (manually or by concurrency group
+  cancellation) while an ARC ephemeral runner is in the process of starting up or
+  acquiring the job message, the runner pod enters a broken state:
+
+  1. The broker sends a "job was canceled" message on the runner's job socket.
+  2. The runner logs: "Skipping message Job. Job message not found 'X'. job was canceled"
+  3. **The runner process does not exit** — it waits for a new job message that
+     will never arrive, because ephemeral runners are single-use and the broker
+     considers this runner's slot exhausted.
+  4. The ARC controller sees the EphemeralRunner pod still in `Running` phase with
+     a live runner process. It does NOT delete and recreate the pod.
+  5. The runner slot is held indefinitely. No new job can be dispatched to this slot.
+     Workflows queue but cannot start, consuming queue capacity without making progress.
+
+  **Secondary failure mode**: After the canceled-job hang, the runner may also
+  attempt to re-acquire its registration token. Since the ephemeral runner's
+  registration was already consumed or expired, this fails with:
+  `Registration 'X' was not found.`
+  The BrokerServer then throws repeatedly, producing a growing error log.
+
+  **Impact**: In a scale set with `minRunners > 0`, each canceled job permanently
+  removes one runner slot from the pool until the pod is manually deleted or the
+  scale set is bounced. With frequent cancellations (e.g., PR pushes with concurrency
+  cancel-in-progress), the pool drains completely and CI halts.
+
+  Source: actions/actions-runner-controller#4307 (Nov 2025, 11 reactions, open).
+  Also related: ARC#4468 (scale set queuing delay during burst) — adjacent but distinct.
+fix: |
+  **Option 1 — Delete stuck EphemeralRunner objects manually (immediate relief):**
+  Identify stuck pods — they have been Running for longer than any expected job
+  duration and show "job was canceled" in their logs:
+
+  ```bash
+  kubectl get ephemerals -n arc-runners --sort-by=.metadata.creationTimestamp
+  kubectl logs <stuck-pod-name> -n arc-runners | grep "job was canceled"
+  kubectl delete ephemeralrunner <stuck-pod-name> -n arc-runners
+  ```
+
+  **Option 2 — Add a watchdog sidecar or CronJob to detect and kill stuck runners:**
+  Run a periodic job that identifies EphemeralRunner pods that have been in Running
+  phase beyond `maxRunnerLifetime` and have no active child processes (no build
+  tools, compilers, or test runners as descendants):
+
+  ```bash
+  # Detect hung runners: Running > 30 min with no CPU activity
+  kubectl get ephemerals -n arc-runners -o json | \
+    jq '.items[] | select(.status.phase=="Running") | .metadata.name'
+  ```
+
+  **Option 3 — Configure autoscaling to replace stuck runners via scale-down:**
+  Set `maxRunners` to a value that triggers KEDA scale-down when load is low.
+  Scale-down deletes idle pods, including stuck ones. Ephemeral runners in the
+  "stuck/waiting" state appear idle to KEDA and will be cleaned up on the next
+  scale-down cycle.
+
+  **Option 4 — Use concurrency groups carefully to reduce cancellations:**
+  Each job cancellation risks creating a stuck runner. Reduce cancellation frequency
+  by scoping concurrency groups more narrowly (per-branch rather than per-repo):
+
+  ```yaml
+  concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+  ```
+
+  **Option 5 — Upgrade ARC and runner image:**
+  Track the upstream fix in ARC#4307. Check ARC release notes for a fix to the
+  runner's post-cancellation cleanup path. Ensure runner image is on the latest
+  minor version.
+fix_code:
+  - language: yaml
+    label: 'Kubernetes CronJob watchdog to delete stuck ARC ephemeral runners'
+    code: |
+      apiVersion: batch/v1
+      kind: CronJob
+      metadata:
+        name: arc-runner-watchdog
+        namespace: arc-runners
+      spec:
+        schedule: "*/10 * * * *"
+        jobTemplate:
+          spec:
+            template:
+              spec:
+                serviceAccountName: arc-runner-watchdog-sa
+                containers:
+                  - name: watchdog
+                    image: bitnami/kubectl:latest
+                    command:
+                      - /bin/sh
+                      - -c
+                      - |
+                        TIMEOUT_MINUTES=30
+                        NOW=$(date +%s)
+                        kubectl get ephemeralrunners -n arc-runners -o json | \
+                          jq -r --argjson now "$NOW" --argjson timeout "$((TIMEOUT_MINUTES * 60))" \
+                          '.items[] | select(.status.phase=="Running") |
+                          select(($now - (.metadata.creationTimestamp | fromdateiso8601)) > $timeout) |
+                          .metadata.name' | \
+                          xargs -r -I{} kubectl delete ephemeralrunner {} -n arc-runners
+                restartPolicy: OnFailure
+  - language: yaml
+    label: 'Narrow concurrency groups to reduce job cancellations hitting ARC'
+    code: |
+      name: CI
+      on:
+        push:
+          branches: ['**']
+        pull_request:
+      concurrency:
+        # Scope to branch — only cancels duplicate runs on the same branch,
+        # not across all branches (reduces how often ARC runners get hit by cancellations)
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+      jobs:
+        build:
+          runs-on:
+            group: my-scale-set
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - "Monitor EphemeralRunner pod ages; any pod in Running phase beyond 2x your longest job duration is likely stuck"
+  - "Use narrow concurrency group scopes (per-branch) to minimize the frequency of job cancellations hitting ARC runners"
+  - "Configure KEDA scale-down (minRunners: 0 during off-hours) to naturally clear stuck runner pods"
+  - "Keep ARC controller and runner image on the latest stable release; the stuck-on-cancel bug has active upstream attention in ARC#4307"
+  - "For high-cancellation workflows (PR push loops), consider using GitHub-hosted runners which handle cancellation cleanup server-side"
+docs:
+  - url: 'https://github.com/actions/actions-runner-controller/issues/4307'
+    label: 'ARC#4307: Ephemeral Runners get stuck when job is canceled or interrupted (11 reactions, open)'
+  - url: 'https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md'
+    label: 'ARC: GitHub Actions Runner Scale Set documentation'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors'
+    label: 'GitHub Docs: Troubleshooting ARC errors'

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

@@ -0,0 +1,132 @@
+id: silent-failures-120
+title: 'github.event.schedule returns stale cron expression for 1-2 runs after updating workflow schedule'
+category: silent-failures
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - github.event.schedule
+  - stale-value
+  - routing
+  - trigger-payload
+patterns:
+  - regex: 'github\.event\.schedule.*[0-9\*\/\-\,]+'
+    flags: 'i'
+  - regex: 'Unknown schedule:\s+[0-9\*\/\-\, ]+'
+    flags: 'i'
+  - regex: 'Evaluating String.*=>\s+''[0-9\*\/\-\, ]+'''
+    flags: 'i'
+error_messages:
+  - "Error: Unknown schedule: 0 5 * * *"
+  - "##[debug]....=> '0 5 * * *'"
+  - "github.event.schedule evaluates to removed cron expression"
+root_cause: |
+  GitHub's schedule dispatcher caches the cron expression strings associated with
+  each workflow internally. When a workflow's `on.schedule` block is updated (cron
+  expression changed or removed) and pushed to the default branch, the dispatcher's
+  internal state does not immediately sync with the new YAML. For 1-2 scheduled runs
+  after the change, the dispatcher fires the workflow with the OLD cron expression
+  in `github.event.schedule`, even though the executed YAML already contains the
+  updated cron string.
+
+  This means:
+  - A workflow with routing logic such as `if: github.event.schedule == '0 5 * * 1-5'`
+    silently skips those steps during the transition window
+  - A `case`/`switch`-style step that branches on `github.event.schedule` hits an
+    "unknown schedule" branch and logs a confusing error
+  - Multi-schedule workflows that use `github.event.schedule` to dispatch different jobs
+    produce wrong results for 1-2 runs post-update
+
+  The stale value typically clears within the next scheduled trigger cycle once the
+  dispatcher re-reads the updated workflow YAML from the default branch. The actual
+  workflow code that runs is the CURRENT version — only the event payload is stale.
+
+  Source: actions/runner#4241 (Feb 2026) — real-world failure confirmed in
+  ava-labs/firewood with stale '0 5 * * *' firing after update to '0 5 * * 1-5',
+  with debug logs showing the old value in the evaluator.
+fix: |
+  **Option 1 — Use a fallback in cron-routing logic:**
+  When switching cron expressions, treat the transition period gracefully by adding
+  the OLD expression to your routing logic temporarily. After 2-3 scheduled cycles,
+  remove the old branch.
+
+  **Option 2 — Avoid routing on github.event.schedule entirely:**
+  Use separate workflow files for each schedule instead of branching inside one
+  workflow on `github.event.schedule`. Each schedule in its own file has an
+  independent dispatch state.
+
+  **Option 3 — Trigger a manual run after updating the schedule:**
+  After pushing the cron change, trigger the workflow via `workflow_dispatch` once.
+  This forces the dispatcher to re-evaluate the workflow file and typically clears
+  the stale state before the next real scheduled run.
+
+  **Option 4 — Accept and handle the stale run:**
+  Add a default/fallback case to your routing logic that gracefully handles an
+  unexpected `github.event.schedule` value rather than erroring:
+
+  ```yaml
+  - name: Route by schedule
+    run: |
+      case "${{ github.event.schedule }}" in
+        '0 5 * * 1-5') echo "Weekday run" ;;
+        '0 5 * * 6')   echo "Saturday run" ;;
+        *)             echo "Unknown schedule (possibly stale): ${{ github.event.schedule }}; skipping" ;;
+      esac
+  ```
+fix_code:
+  - language: yaml
+    label: 'Use separate workflows per schedule (avoids routing entirely)'
+    code: |
+      # weekday-job.yml
+      on:
+        schedule:
+          - cron: '0 5 * * 1-5'
+      jobs:
+        weekday:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Weekday build"
+
+      # saturday-job.yml
+      on:
+        schedule:
+          - cron: '0 5 * * 6'
+      jobs:
+        saturday:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Saturday build"
+  - language: yaml
+    label: 'Graceful fallback case when routing on github.event.schedule'
+    code: |
+      on:
+        schedule:
+          - cron: '0 5 * * 1-5'
+          - cron: '0 5 * * 6'
+      jobs:
+        dispatch:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Route by schedule
+              run: |
+                case "${{ github.event.schedule }}" in
+                  '0 5 * * 1-5') echo "Weekday build" ;;
+                  '0 5 * * 6')   echo "Saturday build" ;;
+                  # Fallback handles stale values during transition window
+                  *)
+                    echo "Unrecognized schedule value: '${{ github.event.schedule }}'"
+                    echo "This may be a stale value from before a recent schedule update."
+                    echo "Skipping; next run should carry the updated expression."
+                    ;;
+                esac
+prevention:
+  - "Never rely on github.event.schedule routing immediately after updating a cron expression; allow 2-3 cycles for dispatcher state to sync"
+  - "Prefer separate workflow files per schedule rather than branching on github.event.schedule inside a single workflow"
+  - "When routing on github.event.schedule is necessary, always include a default/fallback case that handles unexpected values gracefully"
+  - "Trigger a workflow_dispatch run after updating a cron expression to force dispatcher re-evaluation before the next scheduled cycle"
+  - "Add a debug step that logs github.event.schedule at the start of scheduled workflows to surface stale values immediately"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: schedule event'
+  - url: 'https://github.com/actions/runner/issues/4241'
+    label: 'actions/runner#4241: Cron scheduled returns stale cron expression after updating workflow schedule triggers'

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

@@ -0,0 +1,140 @@
+id: silent-failures-121
+title: '`workflow_run: types: [completed]` triggers on ALL conclusions — deploy runs even when CI failed or was cancelled'
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-run
+  - conclusion
+  - silent-failure
+  - deploy-on-failure
+  - ci-cd
+  - workflow-trigger
+  - conclusion-check
+patterns:
+  - regex: 'on:\s*\n\s+workflow_run:'
+    flags: 'im'
+  - regex: 'types:\s*[\[\s]*completed[\]\s]*\n'
+    flags: 'i'
+error_messages:
+  - "# No error message — the deploy workflow runs silently even when upstream CI failed or was cancelled"
+root_cause: |
+  The `workflow_run` event with `types: [completed]` fires whenever the referenced workflow
+  finishes — regardless of its conclusion. A completed workflow can have any of these conclusions:
+  `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`,
+  or `stale`. GitHub fires `workflow_run: completed` for ALL of these states.
+
+  Developers commonly use `workflow_run` to chain a deploy or release workflow after a CI
+  workflow passes. The intuitive reading of "completed" is "finished successfully," but GitHub's
+  semantics are "finished with any outcome":
+
+  ```yaml
+  # ❌ This runs deploy even when CI failed, was cancelled, or was skipped
+  on:
+    workflow_run:
+      workflows: [CI]
+      types: [completed]
+  ```
+
+  Without an explicit `if:` conclusion check, the deploy workflow runs unconditionally after CI —
+  including when CI failed mid-run, was cancelled by a force-push, or was skipped by a path
+  filter. This silently deploys broken code (or publishes, releases, or notifies) whenever CI
+  does not succeed.
+
+  **Why this is a silent failure:**
+  - No error appears — the triggered workflow runs normally and reports "success"
+  - The CI failure and deploy completion appear as separate workflow runs — easy to miss
+  - GitHub does not add a default conclusion filter — the developer must add it manually
+  - The mistake is natural: "trigger when CI is done" sounds equivalent to "trigger when CI passes"
+
+  Sources: GitHub Docs (workflow_run event, conclusion field); SO#62750603 (159 upvotes,
+  152,034 views — top answer recommends adding conclusion check); `ahmadnassri/action-workflow-run-wait`
+  (39 stars — third-party action created specifically to work around this limitation)
+fix: |
+  Add an `if:` condition at the JOB level (not workflow level) to check
+  `github.event.workflow_run.conclusion == 'success'`. Job-level conditions are evaluated at
+  runtime after the event fires, so this reliably gates deployment on CI success.
+
+  Do NOT put the `if:` check at the workflow level — it prevents ALL jobs from running,
+  including any cleanup or notification jobs that should run regardless of conclusion.
+
+  For workflows that need to handle both success and failure (e.g., notify Slack of failures),
+  use separate jobs with different `if:` checks.
+fix_code:
+  - language: yaml
+    label: 'Add conclusion check at the job level — most common fix'
+    code: |
+      name: Deploy
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+
+      jobs:
+        deploy:
+          # ✅ Only deploy when CI succeeded
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # workflow_run always checks out default branch — use ref for PR branches
+                ref: ${{ github.event.workflow_run.head_sha }}
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Branch by conclusion — deploy on success, notify on failure'
+    code: |
+      name: Post-CI Actions
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+
+        notify-failure:
+          if: >-
+            github.event.workflow_run.conclusion == 'failure' ||
+            github.event.workflow_run.conclusion == 'timed_out'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify team of CI failure
+              run: |
+                echo "CI failed on branch ${{ github.event.workflow_run.head_branch }}"
+                # Send Slack/Teams notification here
+  - language: yaml
+    label: 'Anti-pattern: missing conclusion check silently deploys broken code'
+    code: |
+      # ❌ BAD: Runs even when CI failed, was cancelled, or was skipped by path filter
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]   # "completed" means ANY outcome, not just success
+
+      jobs:
+        deploy:
+          # No if: conclusion check — deploys broken code on CI failure!
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Always add `if: github.event.workflow_run.conclusion == 'success'` to deploy/release jobs triggered by workflow_run"
+  - "Remember: 'completed' means the upstream workflow finished — NOT that it succeeded; always check conclusion explicitly"
+  - "Use separate jobs with different `if: conclusion ==` checks for success vs failure vs cancelled handling"
+  - "Consider adding a linting step or actionlint check that flags workflow_run jobs without a conclusion check"
+  - "Test the failure path by intentionally failing CI and verifying the downstream workflow does NOT deploy"
+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 — conclusion field and types'
+  - 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.event.workflow_run context properties'
+  - url: 'https://stackoverflow.com/questions/62750603/github-actions-trigger-another-action-after-one-action-is-completed'
+    label: 'SO #62750603: Trigger action after completion — top answer adds conclusion check (159 upvotes, 152k views)'
+  - url: 'https://github.com/ahmadnassri/action-workflow-run-wait'
+    label: 'ahmadnassri/action-workflow-run-wait — third-party action created to wait for successful workflow_run'

package/errors/triggers/triggers-074.yml

@@ -0,0 +1,142 @@
+id: triggers-074
+title: '`workflow_run: branches:` filter silently never triggers when upstream was started by `schedule` or `workflow_dispatch` — `head_branch` is null'
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-run
+  - branches-filter
+  - head-branch
+  - schedule
+  - workflow-dispatch
+  - null
+  - silent-failure
+  - trigger-missing
+patterns:
+  - regex: 'on:\s*\n\s+workflow_run:\s*\n(.|\n)*?branches:\s*\n'
+    flags: 'im'
+  - regex: 'workflow_run.*branches.*schedule\s*$|schedule.*workflow_run.*branches'
+    flags: 'im'
+error_messages:
+  - "# No error message — the downstream workflow simply never runs when upstream was triggered by schedule or workflow_dispatch"
+root_cause: |
+  The `workflow_run` event exposes a `branches:` filter that is supposed to limit which upstream
+  workflow run conclusions trigger the downstream workflow. The filter compares against
+  `github.event.workflow_run.head_branch`.
+
+  **The problem:** When the upstream workflow is triggered by a `schedule` or `workflow_dispatch`
+  event, GitHub sets `head_branch` to `null` (not a branch name). The `branches:` filter then
+  evaluates `null` against each pattern in the list — and null never matches any branch name
+  pattern, including `[main]`, `['**']`, or any glob. The downstream workflow silently never
+  triggers, even though the upstream ran successfully on main.
+
+  **Event types that produce null head_branch:**
+  - `schedule` — cron-triggered workflows have no associated branch context
+  - `workflow_dispatch` — manually dispatched workflows MAY have null head_branch in some cases
+
+  **Pull request triggers correctly populate head_branch** (the PR head branch name), and
+  `push` triggers also correctly populate it (the pushed branch name). The null behavior is
+  specific to schedule and dispatch events on the upstream.
+
+  **Why this is a silent failure:**
+  - No error is raised — the downstream workflow simply does not appear in the Actions UI for that run
+  - The upstream workflow runs and completes successfully
+  - The `branches:` filter looks correct — `[main]` is the right branch name
+  - The issue only manifests for schedule/dispatch-triggered upstream runs; if CI also triggers
+    on push to main, push-triggered runs DO reach the downstream workflow
+
+  **Example scenario:** A deploy workflow runs after CI. CI has `on: [push, schedule]`.
+  The `branches: [main]` filter in the deploy's workflow_run block works for push events but
+  silently skips all scheduled CI runs.
+
+  Sources: GitHub Docs (workflow_run, head_branch null for schedule); community/discussions
+  related to workflow_run not triggering after schedule; documented in
+  `workflow-run-head-branch-null-schedule-dispatch-concurrency.yml` (concurrency variant)
+fix: |
+  Remove the `branches:` filter from the `workflow_run` trigger entirely and instead use a
+  job-level `if:` condition to check the branch after the event fires. The `if:` condition
+  evaluates at runtime and can handle null gracefully.
+
+  For schedule-triggered upstreams, use `github.event.workflow_run.head_branch == 'main' ||
+  github.event.workflow_run.head_branch == null` (null means it ran from the default branch).
+
+  Alternatively, filter by the workflow run's `head_sha` and check against known branch SHAs.
+fix_code:
+  - language: yaml
+    label: 'Remove branches filter and add job-level if condition — handles schedule and dispatch'
+    code: |
+      name: Deploy After CI
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          # ❌ Do NOT use branches: here if CI runs on schedule or workflow_dispatch
+          # branches: [main]   # This silently skips all schedule-triggered CI runs
+
+      jobs:
+        deploy:
+          # ✅ Use job-level if: instead of trigger-level branches:
+          # null head_branch means schedule/dispatch from default branch — include it
+          if: >-
+            github.event.workflow_run.conclusion == 'success' &&
+            (github.event.workflow_run.head_branch == 'main' ||
+             github.event.workflow_run.head_branch == null)
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'When upstream is push-only: branches filter works fine (head_branch is always set)'
+    code: |
+      name: Deploy After CI (push-only upstream)
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          # ✅ branches: filter works correctly ONLY when upstream runs on push or pull_request
+          # Because push and pull_request events always set head_branch
+          branches: [main]
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+
+      # ⚠️ If CI also has on: schedule — add null check above or remove branches: filter
+  - language: yaml
+    label: 'Anti-pattern: branches filter with schedule-triggered upstream — downstream never fires'
+    code: |
+      # ❌ BAD: Upstream CI has on: [push, schedule]
+      # But deploy's branches filter silently skips all scheduled CI runs
+
+      name: Deploy After CI
+
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          branches: [main]   # null (from schedule) never matches 'main' — deploy skipped!
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh   # Never runs after scheduled CI
+prevention:
+  - "Avoid `branches:` filter in workflow_run if the upstream workflow can be triggered by `schedule` or `workflow_dispatch`"
+  - "Use job-level `if:` conditions with explicit null handling instead of trigger-level branch filters"
+  - "Check the upstream workflow's triggers — if it includes `schedule` or `workflow_dispatch`, `head_branch` will be null for those runs"
+  - "Test by triggering the upstream workflow manually and verifying the downstream workflow appears in the Actions UI"
+  - "When null head_branch is acceptable (schedule from default branch), use `head_branch == 'main' || head_branch == null`"
+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 — branches filter and head_branch field'
+  - 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.event.workflow_run — head_branch property (null for schedule/dispatch)'
+  - url: 'https://github.com/orgs/community/discussions/26238'
+    label: 'GitHub Community: workflow_run not triggering — head_branch null discussion'

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

@@ -0,0 +1,141 @@
+id: yaml-syntax-077
+title: 'VS Code GitHub Actions extension / languageservices emits false "Context access might be invalid" warning for secrets.*, vars.*, needs.* in valid regular workflows'
+category: yaml-syntax
+severity: warning
+tags:
+  - vscode
+  - languageservices
+  - false-positive
+  - secrets-context
+  - vars-context
+  - needs-context
+  - linting
+  - actionlint
+patterns:
+  - regex: 'Context access might be invalid:\s+secrets\.'
+    flags: 'i'
+  - regex: 'Context access might be invalid:\s+vars\.'
+    flags: 'i'
+  - regex: 'Context access might be invalid:\s+needs\.'
+    flags: 'i'
+  - regex: 'Unrecognized named-value:\s+''secrets'''
+    flags: 'i'
+error_messages:
+  - "Context access might be invalid: secrets.MY_SECRET"
+  - "Context access might be invalid: vars.MY_VAR"
+  - "Context access might be invalid: needs.build.outputs.artifact-path"
+  - "Unrecognized named-value: 'secrets'"
+root_cause: |
+  The VS Code GitHub Actions extension (github.vscode-github-actions) uses the
+  `@actions/languageservices` package for workflow linting and IntelliSense. The
+  language server performs static analysis without access to the repository's actual
+  secrets, variables, or environment configuration. It emits "Context access might
+  be invalid" warnings in several scenarios where the workflow is in fact correct:
+
+  1. **Repository-level secrets and variables**: The language server cannot query
+     the repository's secrets or variables store, so any `secrets.MY_SECRET` or
+     `vars.MY_VAR` reference triggers a warning. This affects every workflow that
+     uses custom secrets or variables — i.e., nearly all real-world workflows.
+
+  2. **Dynamic environment secrets**: When a workflow uses `environment: ${{ ... }}`
+     with an expression to select the environment at runtime, the language server
+     cannot statically resolve which environment's secrets are accessible. Even
+     validly scoped `secrets.*` references under dynamic environments are flagged.
+
+  3. **needs.* context across complex job dependency graphs**: The language server
+     sometimes flags `needs.X.outputs.Y` as invalid when job X is defined in the
+     same workflow but the graph is not trivially linear, or when `needs:` contains
+     a list of multiple dependencies.
+
+  **Why this is a false positive:**
+  The warnings are generated by the language server's static type system, which
+  requires compile-time knowledge of what secrets/variables exist. GitHub Actions
+  resolves these at runtime from the repository/organization secrets store — a
+  source the language server has no access to. The workflow runs correctly at
+  runtime; only the editor shows red squiggles.
+
+  This is an open known issue tracked in actions/languageservices#239 (assigned
+  to GitHub staff, reopened after partial fixes). Multiple VS Code extension issues
+  document the same root cause: vscode-github-actions#461, #452, #375, #533.
+
+  **Scope**: Affects anyone using the VS Code GitHub Actions extension
+  (github.vscode-github-actions) v0.x and v1.x with workflows using secrets,
+  variables, or multi-job dependency outputs. NOT an actionlint issue —
+  actionlint correctly handles these cases without false positives.
+fix: |
+  **Option 1 — Suppress per-line (extension-specific comment):**
+  The language server respects `# ignore` comments to suppress specific warnings.
+  Add a comment on the line preceding the flagged expression:
+
+  ```yaml
+  env:
+    # ignore: context-access-might-be-invalid
+    MY_VAR: ${{ secrets.MY_SECRET }}
+  ```
+
+  Note: This syntax is not standardized and may change with extension updates.
+
+  **Option 2 — Disable specific diagnostics in VS Code settings:**
+  In `.vscode/settings.json`, disable the diagnostic class:
+
+  ```json
+  {
+    "github-actions.workflows.pinned.refresh.enabled": true
+  }
+  ```
+
+  **Option 3 — Ignore and trust runtime behavior:**
+  This is a false positive — the workflow will run correctly. If the warning is
+  distracting, the safest approach is to acknowledge it as a known extension
+  limitation and verify by running the workflow. GitHub Actions runtime correctly
+  resolves secrets, vars, and needs contexts.
+
+  **Option 4 — Use actionlint for CI-level linting (no false positives for secrets):**
+  `actionlint` does not flag `secrets.*` references as invalid (it correctly
+  treats them as opaque strings). For CI integration, prefer actionlint over
+  the VS Code extension's linter for automated checks.
+fix_code:
+  - language: yaml
+    label: 'Workflow using secrets and vars — runs correctly despite VS Code warnings'
+    code: |
+      # This workflow is valid — VS Code warns but GitHub Actions runs it correctly.
+      # The "Context access might be invalid" warnings for secrets.* and vars.*
+      # are false positives from the languageservices static analyzer.
+      name: Deploy
+      on:
+        push:
+          branches: [main]
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production
+          steps:
+            - name: Use secret (VS Code may warn here — ignore it)
+              run: echo "Deploying..."
+              env:
+                API_KEY: ${{ secrets.API_KEY }}         # false positive warning
+                BASE_URL: ${{ vars.DEPLOY_BASE_URL }}   # false positive warning
+  - language: json
+    label: 'VS Code settings.json — disable noisy extension diagnostics'
+    code: |
+      {
+        "github-actions.workflows.pinned.refresh.enabled": true,
+        "github-actions.org-secrets.enabled": false
+      }
+prevention:
+  - "Do not suppress workflow secrets or variables based on VS Code warnings — verify by actually running the workflow"
+  - "Use actionlint for CI-integrated linting; it handles secrets/vars correctly without false positives"
+  - "Keep the VS Code GitHub Actions extension updated; GitHub staff are actively working on reducing false positives in languageservices"
+  - "Check the languageservices GitHub repo (actions/languageservices) for known false positive issues before filing new bugs"
+  - "When sharing workflow snippets, note that VS Code warnings do not necessarily indicate real problems — always confirm against actual run output"
+docs:
+  - url: 'https://github.com/actions/languageservices/issues/239'
+    label: 'actions/languageservices#239: Context access might be invalid is too aggressive (open, assigned)'
+  - url: 'https://github.com/github/vscode-github-actions/issues/461'
+    label: 'vscode-github-actions#461: Unrecognized Github Actions Secret Context (false positive)'
+  - url: 'https://github.com/github/vscode-github-actions/issues/452'
+    label: 'vscode-github-actions#452: False warning for actions/checkout: Context access might be invalid'
+  - url: 'https://github.com/github/vscode-github-actions/issues/375'
+    label: 'vscode-github-actions#375: false positive error on secrets context access in forks'
+  - url: 'https://github.com/rhysd/actionlint'
+    label: 'actionlint: alternative linter that handles secrets/vars without false positives'

package/package.json

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