@htekdev/actions-debugger 1.0.129 → 1.0.131

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-241.yml

@@ -0,0 +1,154 @@
+id: runner-environment-241
+title: 'Docker container fails with "openat etc/passwd: path escapes from parent" on containerd v2.2+'
+category: runner-environment
+severity: error
+tags:
+  - containerd
+  - docker
+  - healthcheck
+  - path-escapes
+  - nixos
+  - absolute-symlink
+  - runner-image-update
+patterns:
+  - regex: 'openat etc/passwd: path escapes from parent'
+    flags: 'i'
+  - regex: 'openat etc/group: path escapes from parent'
+    flags: 'i'
+  - regex: 'ExitCode.*-1.*path escapes|path escapes.*ExitCode.*-1'
+    flags: 'i'
+  - regex: 'mount callback failed.*path escapes from parent'
+    flags: 'i'
+error_messages:
+  - "openat etc/passwd: path escapes from parent"
+  - "openat etc/group: path escapes from parent"
+  - "mount callback failed on /tmp/containerd-mount...: openat etc/passwd: path escapes from parent"
+  - "ExitCode: -1 (exit code -1)"
+root_cause: |
+  containerd v2.2.0+ (built with Go 1.24) introduced stricter path validation via Go 1.24's
+  `os.Root` API. When Docker starts or runs a health check on a container whose image has
+  `/etc/passwd` or `/etc/group` symlinked to an **absolute path** (e.g., NixOS images where
+  `/etc/passwd → /nix/store/.../passwd`), containerd misinterprets the symlink target as
+  escaping the container root filesystem and raises:
+  `openat etc/passwd: path escapes from parent`.
+
+  **Affected container images:**
+  - **NixOS-based images** (e.g., `nixos/nix:latest`) — `/etc/passwd → /nix/store/.../passwd`
+  - **ngrok container images** — use absolute symlinks for system files
+  - **Android emulator images** — `/etc` itself may be an absolute symlink to `/system/etc`
+  - Any image where the symlink target for `/etc/passwd` or `/etc/group` starts with `/`
+
+  **Impact on GitHub Actions workflows:**
+  1. Service containers with HEALTHCHECK definitions fail with `ExitCode: -1` even when the
+     service is actually running correctly
+  2. Container jobs (`container: image: nixos/nix:latest`) fail at startup before any steps run
+  3. Docker `run` steps using affected images fail with `path escapes from parent` in logs
+
+  **Status on GitHub-hosted runners:**
+  - **Windows runners** (windows-2022, windows-2025, windows-11-arm64): containerd v2.2.x
+    shipped with Docker 29 on February 9, 2026 — **currently affected**
+  - **Ubuntu runners**: containerd v2.2.x deployed February 9, 2026 then **rolled back on
+    February 20, 2026** due to this and related issues (runner-images#13682, #13684, #13691);
+    tracked for re-deployment in runner-images#14105
+
+  A partial fix was merged in containerd v2.2.2 (commit 85b5418e) addressing the case where
+  `/etc/passwd` itself is a direct absolute symlink. However, the case where an **intermediate
+  directory** (e.g., `/etc` is an absolute symlink to `/system/etc`) remains broken and open
+  in containerd#13382 as of May 2026.
+
+  Source: actions/runner-images#13682 (Feb 2026), containerd/containerd#12683,
+  reubeno/brush#999 (real-world GitHub Actions failure)
+fix: |
+  **Option 1 — Convert absolute symlinks to relative in a pre-step (most portable fix):**
+  Add a step before any Docker operations that resolves absolute `/etc/passwd` and
+  `/etc/group` symlinks to relative equivalents inside the container. This approach works
+  even when you cannot modify the container image.
+
+  **Option 2 — Build a derived image with relative symlinks:**
+  Create a `Dockerfile` that `FROM` the affected image and replaces the absolute symlinks
+  with relative ones. This is the most reliable long-term fix when you own the workflow.
+
+  **Option 3 — Use an alternative image without absolute symlinks:**
+  Standard Ubuntu, Debian, and Alpine images use regular files (not symlinks) for
+  `/etc/passwd` and `/etc/group` — they are unaffected. If the workflow can use a
+  different base image, this sidesteps the issue entirely.
+
+  **Option 4 — Pin containerd to v2.1.x on self-hosted runners:**
+  On self-hosted runners where you control Docker/containerd versions, remain on
+  containerd v1.7.x or v2.1.x until containerd v2.2.3+ resolves all absolute symlink cases.
+fix_code:
+  - language: yaml
+    label: 'Workaround — convert absolute /etc symlinks in a pre-step (NixOS/ngrok containers)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          container:
+            image: nixos/nix:latest
+          steps:
+            - name: Fix absolute /etc symlinks (containerd v2.2+ workaround)
+              run: |
+                for f in /etc/passwd /etc/group; do
+                  if [ -L "$f" ]; then
+                    target=$(readlink "$f")
+                    if echo "$target" | grep -q '^/'; then
+                      # Convert absolute symlink to relative
+                      rel=$(python3 -c "import os; print(os.path.relpath('$target', '/etc'))")
+                      ln -sf "$rel" "$f"
+                    fi
+                  fi
+                done
+            - name: Run tests
+              run: nix run nixpkgs#hello
+
+  - language: yaml
+    label: 'Build a derived image that replaces absolute symlinks with relative ones'
+    code: |
+      # Dockerfile.fixed — used for CI to avoid the containerd v2.2 regression:
+      # FROM nixos/nix:latest
+      # RUN for f in /etc/passwd /etc/group; do \
+      #       if [ -L "$f" ]; then \
+      #         target=$(readlink "$f"); \
+      #         rel=$(python3 -c "import os; print(os.path.relpath('$target', '/etc'))"); \
+      #         ln -sf "$rel" "$f"; \
+      #       fi; \
+      #     done
+
+      # In workflow — build derived image first:
+      steps:
+        - name: Build patched image
+          run: docker build -f Dockerfile.fixed -t my-nix-fixed .
+
+        - name: Use patched image
+          run: docker run --rm my-nix-fixed nix run nixpkgs#hello
+
+  - language: yaml
+    label: 'Use Alpine or Debian service container instead of NixOS/ngrok'
+    code: |
+      # Unaffected base images (no absolute symlinks for /etc/passwd):
+      # redis:7-alpine, postgres:16-alpine, debian:bookworm-slim, ubuntu:24.04
+      jobs:
+        test:
+          runs-on: windows-2025    # Docker 29 + containerd v2.2 — always active on Windows
+          services:
+            redis:
+              image: redis:7-alpine
+              options: >-
+                --health-cmd "redis-cli ping"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+prevention:
+  - 'Never use NixOS, ngrok, or Android emulator container images as service containers on Windows runners without the absolute-symlink workaround — Windows runners have had containerd v2.2.x since Feb 2026.'
+  - 'Check if your container image uses absolute /etc/passwd symlinks with: `docker run --rm <image> readlink /etc/passwd`. If the output starts with "/", it will fail on containerd v2.2+.'
+  - 'Use official distribution base images (Alpine, Debian, Ubuntu) for service containers when possible — they use regular files for /etc/passwd and are unaffected.'
+  - 'Monitor runner-images#14105 for the Ubuntu Docker 29 re-deployment timeline — once Ubuntu runners re-deploy Docker 29, this issue will re-appear on Linux jobs as well.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13682'
+    label: 'runner-images#13682 — Container healthchecks failing with path escapes on Ubuntu runners'
+  - url: 'https://github.com/containerd/containerd/issues/12683'
+    label: 'containerd#12683 — v2.2.0 fails to create containers with /etc/passwd as absolute symlink'
+  - url: 'https://github.com/containerd/containerd/issues/13382'
+    label: 'containerd#13382 — v2.2+ fails when /etc directory itself is an absolute symlink'
+  - url: 'https://github.com/reubeno/brush/issues/999'
+    label: 'brush#999 — Real-world GitHub Actions failure with nixos/nix container'

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

@@ -0,0 +1,131 @@
+id: runner-environment-242
+title: 'Docker Engine v29 raises minimum API to 1.44 — old SDK clients fail with "client version X is too old"'
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-29
+  - api-version
+  - sdk
+  - windows
+  - runner-image-update
+  - python-docker
+patterns:
+  - regex: 'client version \d+\.\d+ is too old\. Minimum supported API version is 1\.4[4-9]'
+    flags: 'i'
+  - regex: 'Error response from daemon: client version.*Minimum supported API version is 1\.4[4-9]'
+    flags: 'i'
+  - regex: 'minimum supported API version.*1\.4[4-9]|API version.*too old.*upgrade your client'
+    flags: 'i'
+error_messages:
+  - "Error response from daemon: client version 1.41 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"
+  - "Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"
+  - "Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version"
+root_cause: |
+  Docker Engine v29.0 (released November 2025) raised the **minimum supported Docker daemon
+  API version from 1.24 to 1.44**. Any Docker SDK client that negotiates API version 1.43 or
+  lower receives:
+  `"Error response from daemon: client version 1.41 is too old. Minimum supported API version
+  is 1.44, please upgrade your client to a newer version"`.
+
+  **API version 1.44 corresponds to Docker Engine 23.0**. Any SDK client built against Docker
+  < 23.0 will fail when the daemon is Docker Engine v29+.
+
+  **Impact on GitHub Actions — current status:**
+  - **Windows runners** (windows-2022, windows-2025, windows-11-arm64): Docker 29.x deployed
+    February 9, 2026 — **currently affected on Windows workflows**
+  - **Ubuntu runners**: Docker 29.x rolled back February 20, 2026 due to related issues
+    (runner-images#13682, #13684); re-deployment tracked in runner-images#14105
+
+  **Affected tools and workflows:**
+  - Python `docker` library ≤ 6.1.3 (negotiates API 1.41 by default) — upgrade to ≥ 7.0.0
+  - `google/oss-fuzz` CIFuzz action — uses internal Python docker client negotiating API 1.41;
+    affected every project using `google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master`
+  - Go `github.com/docker/docker/client` packages pinned to Docker < 23.0 API
+  - Any workflow tool, action, or custom script that embeds its own Docker SDK rather than
+    invoking the CLI `docker` command
+  - GitHub Codespaces dev container CI workflows using Docker SDK library in test scripts
+
+  **Note:** This is distinct from the Docker Compose v1/v2 breaking changes (see
+  `docker-29-compose-v2-40-breaking.yml` / re-031), which covers Compose CLI changes.
+  This entry covers SDK API negotiation failures from non-CLI Docker clients.
+
+  Source: google/oss-fuzz#14945 (Feb 2026), actions/runner-images#13474, docker/docs#23910
+fix: |
+  **Option 1 — Upgrade Python docker library to ≥ 7.0.0:**
+  The most common case. Python docker SDK ≥ 7.0.0 negotiates API 1.47+ which is compatible
+  with Docker Engine 29.
+
+  **Option 2 — Use the Docker CLI instead of SDK calls:**
+  Replace Python/Go SDK calls with `docker build`, `docker run`, etc. via `run:` steps. The
+  Docker CLI always negotiates the correct API version with the daemon automatically.
+
+  **Option 3 — Set DOCKER_API_VERSION environment variable:**
+  Some SDKs honor `DOCKER_API_VERSION=1.44` as an override. However this only works if the
+  SDK actually implements the 1.44 protocol — just setting the env var won't upgrade an
+  SDK that doesn't support 1.44.
+
+  **Option 4 — Pin the affected tool to an updated version:**
+  For CIFuzz: the fix was deployed to `google/oss-fuzz` within hours of the issue being
+  reported. Pin `@master` to get the fix, or wait for a tagged release. For any other
+  action/tool embedding Docker SDK, check for an updated release that bumps the SDK.
+fix_code:
+  - language: yaml
+    label: 'Upgrade Python docker SDK in workflow before using it'
+    code: |
+      # The error appears in workflows using Python docker library <= 6.1.3
+      # Example error:
+      #   Error response from daemon: client version 1.41 is too old.
+      #   Minimum supported API version is 1.44
+      steps:
+        - name: Upgrade Docker Python SDK
+          run: pip install 'docker>=7.0.0'
+
+        - name: Run Docker-based tests
+          run: python -m pytest tests/docker/
+
+  - language: yaml
+    label: 'Replace SDK docker.from_env() calls with Docker CLI'
+    code: |
+      # Instead of Python SDK:
+      #   import docker
+      #   client = docker.from_env()
+      #   client.images.build(path='.', tag='my-image')
+      # Use the CLI directly via shell steps:
+      steps:
+        - name: Build Docker image
+          run: docker build -t my-image:latest .
+
+        - name: Run container
+          run: docker run --rm my-image:latest ./run-tests.sh
+
+        - name: Push to registry
+          run: docker push my-image:latest
+
+  - language: yaml
+    label: 'Check Docker API version compatibility in your workflow'
+    code: |
+      # Run this step to diagnose version negotiation issues:
+      steps:
+        - name: Show Docker version information
+          run: |
+            docker version
+            # Server.APIVersion: 1.47  (what the daemon offers)
+            # Client.APIVersion: 1.47  (what the CLI uses — always current)
+            # If using Python sdk: python3 -c "import docker; c=docker.from_env(); print(c.version())"
+            # If sdk prints error about client version, upgrade docker>=7.0.0
+prevention:
+  - 'Avoid embedding Docker SDK client calls in workflow scripts — always prefer the Docker CLI via run: steps, which auto-negotiates the correct API version.'
+  - 'When the Python docker library IS required, pin it to >=7.0.0 in requirements.txt or install it explicitly in a workflow step before use.'
+  - 'Test workflows on windows-2025 before ubuntu re-deployment of Docker 29 — Windows runners already expose the Docker 29 min API 1.44 constraint.'
+  - 'If using google/oss-fuzz CIFuzz, ensure you reference a recent commit — the fix for API 1.41 incompatibility was deployed in Feb 2026.'
+  - 'When adding new tool dependencies that use Docker, check the docker-py version they require and whether it supports API >= 1.44.'
+docs:
+  - url: 'https://github.com/google/oss-fuzz/issues/14945'
+    label: 'oss-fuzz#14945 — CIFuzz fails with client version 1.41 too old after Docker v29 update'
+  - url: 'https://github.com/actions/runner-images/issues/13474'
+    label: 'runner-images#13474 — Docker 29.1.* update announcement (Feb 9, 2026)'
+  - url: 'https://docs.docker.com/reference/api/engine/'
+    label: 'Docker Engine API reference — version compatibility matrix'
+  - url: 'https://github.com/actions/runner-images/issues/14105'
+    label: 'runner-images#14105 — Docker v29 Ubuntu re-deployment tracking issue'

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

@@ -0,0 +1,120 @@
+id: runner-environment-243
+title: 'macOS 26 runner — Xcode_26.0.app path does not exist; only Xcode_26.0.1.app is installed'
+category: runner-environment
+severity: error
+tags:
+  - macos-26
+  - xcode
+  - xcode-select
+  - sdk-not-found
+  - runner-image
+  - ios
+  - version-naming
+patterns:
+  - regex: 'SDK.*Xcode_26\.0\.app.*cannot be located|Xcode_26\.0\.app.*SDK.*cannot be located'
+    flags: 'i'
+  - regex: 'xcode-select.*Xcode_26\.0\.app.*no such file|invalid developer directory.*Xcode_26\.0\.app'
+    flags: 'i'
+  - regex: 'xcodebuild: error: SDK.*Xcode_26\.0[^.1].*cannot be located'
+    flags: 'i'
+  - regex: '/Applications/Xcode_26\.0\.app.*does not exist'
+    flags: 'i'
+error_messages:
+  - "xcodebuild: error: SDK \"/Applications/Xcode_26.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk\" cannot be located."
+  - "xcode-select: error: invalid developer directory '/Applications/Xcode_26.0.app/Contents/Developer'"
+  - "error: '/Applications/Xcode_26.0.app' does not exist or is not a directory"
+root_cause: |
+  On `macos-26` and `macos-26-arm64` runners, Xcode applications are installed with their
+  **full version number including patch** in the directory name:
+  - `Xcode_26.0.1.app` — NOT `Xcode_26.0.app`
+  - `Xcode_26.2.app`
+  - `Xcode_26.4.1.app` — NOT `Xcode_26.4.app`
+
+  Workflows that hardcode `/Applications/Xcode_26.0.app` in `xcode-select --switch` or in
+  `DEVELOPER_DIR` environment variables fail immediately because the path does not exist.
+  No backward-compatible symlink (`Xcode_26.0.app → Xcode_26.0.1.app`) is created.
+
+  **Why this changed:** Starting with Xcode 26, Apple's versioning scheme includes a patch
+  component (major.minor.patch) that is reflected in the installed application directory name
+  when the patch is non-zero. This differs from Xcode 16 and earlier where the directory name
+  omitted the patch (e.g., `Xcode_16.4.app` is actually Xcode 16.4.0).
+
+  **Note on the "26.0" naming gap:** The first generally-available Xcode for macOS 26 was
+  Xcode 26.0.1 (not 26.0.0). This means `Xcode_26.0.app` was never installed — the runner
+  image went straight from having no Xcode 26 to having `Xcode_26.0.1.app`.
+
+  Source: actions/runner-images#13743 (Feb 2026)
+fix: |
+  **Option 1 — Use maxim-lobanov/setup-xcode action (recommended):**
+  This action resolves Xcode paths dynamically from the runner's installed versions and
+  handles the naming scheme automatically. Specify an exact version like `'26.0.1'` or
+  `'latest-stable'`.
+
+  **Option 2 — Hardcode the full version including patch:**
+  Replace `Xcode_26.0.app` with `Xcode_26.0.1.app`. Always check the runner image Readme
+  for the exact installed filename before pinning.
+
+  **Option 3 — List available versions at runtime:**
+  Add a discovery step that lists `/Applications/Xcode*.app/` and uses the result to
+  select the correct version dynamically.
+fix_code:
+  - language: yaml
+    label: 'Use setup-xcode to resolve Xcode path automatically (recommended)'
+    code: |
+      # setup-xcode handles the naming scheme and patches for you
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.0.1'   # full version including patch
+
+            - name: Build
+              run: xcodebuild -scheme MyApp -destination generic/platform=iOS build
+
+  - language: yaml
+    label: 'Pin correct full-patch version in xcode-select --switch'
+    code: |
+      # Wrong — path does not exist on macos-26:
+      # - run: sudo xcode-select --switch /Applications/Xcode_26.0.app/Contents/Developer
+
+      # Correct — include the patch version:
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - name: Select Xcode 26.0.1
+              run: sudo xcode-select --switch /Applications/Xcode_26.0.1.app/Contents/Developer
+
+            - name: Verify Xcode version
+              run: xcodebuild -version
+
+  - language: yaml
+    label: 'Discover installed Xcode versions at runtime'
+    code: |
+      # Add a discovery step to find what is actually installed:
+      steps:
+        - name: List installed Xcode versions
+          run: |
+            echo "Available Xcode installations:"
+            ls -la /Applications/Xcode*.app/ 2>/dev/null | awk '{print $NF}'
+            echo ""
+            echo "Currently selected Xcode:"
+            xcode-select -p
+            xcodebuild -version
+
+prevention:
+  - 'Never hardcode Xcode application directory paths — use maxim-lobanov/setup-xcode@v1 with a specific xcode-version that includes the patch number.'
+  - 'When pinning a path is required, always look up the exact installed path in the runner image Readme: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md#xcode'
+  - 'For Xcode 26.x, always include the patch in version strings: "26.0.1" not "26.0", "26.4.1" not "26.4".'
+  - 'Subscribe to runner-images announcements to get advance notice of Xcode version updates that change installed paths.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13743'
+    label: 'runner-images#13743 — Xcode 26.0 symlink not working on macos-26 (Feb 2026)'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md'
+    label: 'macOS 26 arm64 runner image Readme — installed Xcode versions'
+  - url: 'https://github.com/maxim-lobanov/setup-xcode'
+    label: 'maxim-lobanov/setup-xcode — recommended action for Xcode version selection'

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

@@ -0,0 +1,136 @@
+id: runner-environment-244
+title: 'macOS 26 — iOS/watchOS/tvOS 26.0 simulator runtimes removed when Xcode 26.4 GA deployed'
+category: runner-environment
+severity: error
+tags:
+  - macos-26
+  - xcode
+  - ios-simulator
+  - simulator-runtime
+  - xcodebuild
+  - runtime-removed
+  - runner-image-update
+patterns:
+  - regex: 'Unable to find a destination matching the provided destination specifier.*OS:26\.0[^.]'
+    flags: 'i'
+  - regex: 'Unable to boot.*Simulator.*26\.0[^.].*unavailable|The destination.*iOS.*26\.0[^.].*not available'
+    flags: 'i'
+  - regex: 'Could not find a simulator runtime for.*26\.0[^.]|No matching destinations for.*OS.*26\.0'
+    flags: 'i'
+  - regex: 'simulator.*OS=26\.0[^.][^0-9].*not found|destination.*platform=iOS Simulator.*OS:26\.0[^.].*unavailable'
+    flags: 'i'
+error_messages:
+  - "xcodebuild: error: Unable to find a destination matching the provided destination specifier: { platform:iOS Simulator, OS:26.0 }"
+  - "Unable to boot the Simulator. The request to boot 'iOS 26.0 Simulator' was denied because the destination is incompatible with this version of Xcode."
+  - "Could not find a simulator runtime for 'iOS 26.0'"
+  - "No matching destinations for { platform:iOS Simulator, OS:26.0 }"
+root_cause: |
+  On April 1, 2026, GitHub merged runner-images PR #13875 which moved Xcode 26.4 from Release
+  Candidate to GA on `macos-26` and `macos-26-arm64` runner images. As part of this change:
+
+  - **Added:** iOS 26.4, watchOS 26.4, tvOS 26.4, visionOS 26.4 simulator runtimes
+  - **Removed:** iOS 26.0.1, watchOS 26.0.1, tvOS 26.0.1, visionOS 26.0.1 simulator runtimes
+
+  GitHub Actions images support **at most three runtime sets per Xcode** due to disk space
+  constraints (documented in macos-15-xcode-simulator-sdk-policy.yml). When a new runtime set
+  is added, the oldest is removed.
+
+  **Affected workflows:**
+  - Workflows that pin `OS:26.0` in xcodebuild `-destination` strings (e.g.,
+    `-destination 'platform=iOS Simulator,name=iPhone 16,OS=26.0'`)
+  - Workflows using `xcrun simctl list runtimes` that previously found `iOS 26.0` and now
+    find only `iOS 26.2` and `iOS 26.4` (or later versions)
+  - `fastlane scan` or similar tools configured with a hardcoded iOS 26.0 simulator target
+  - Any tooling that generates test matrices including `iOS 26.0` destinations
+
+  Simulator runtimes **currently available** on macos-26 after the April 1 change:
+  - iOS 26.2 + watchOS 26.2 + tvOS 26.2 + visionOS 26.2
+  - iOS 26.4 + watchOS 26.4 + tvOS 26.4 + visionOS 26.4
+  (The exact installed runtimes change with each Xcode GA deployment. Always check the runner
+  image Readme for the current set.)
+
+  Source: actions/runner-images PR #13875 (merged April 1, 2026), runner-images#13853
+fix: |
+  **Option 1 — Update destination to use an available runtime version:**
+  Replace `OS:26.0` with `OS:26.4` (or `latest-available`) in xcodebuild destination strings.
+  Pin to a specific available version to avoid future breakage.
+
+  **Option 2 — Use `latest-available` as the OS version:**
+  Some xcodebuild invocations accept `OS:latest-available` as the OS specifier, which picks
+  the newest installed runtime matching the platform. This avoids hard-coding a version.
+
+  **Option 3 — Use the maxim-lobanov/setup-ios-simulator action:**
+  This action can download and install a specific simulator runtime on demand, decoupling
+  your workflow from what is pre-installed on the runner image.
+
+  **Option 4 — Query available runtimes at runtime and select dynamically:**
+  Use `xcrun simctl list runtimes` to discover what is installed before running tests, then
+  construct the `-destination` argument from the actual available runtimes.
+fix_code:
+  - language: yaml
+    label: 'Update destination to latest available simulator runtime'
+    code: |
+      jobs:
+        test-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: 'latest-stable'
+
+            # Wrong — iOS 26.0 runtime no longer installed:
+            # - run: xcodebuild test -scheme MyApp
+            #            -destination 'platform=iOS Simulator,name=iPhone 16,OS=26.0'
+
+            # Correct — use an installed runtime version:
+            - name: Run iOS tests
+              run: |
+                xcodebuild test \
+                  -scheme MyApp \
+                  -destination 'platform=iOS Simulator,name=iPhone 16,OS=26.4'
+
+  - language: yaml
+    label: 'Use latest-available OS version to avoid future runtime removals'
+    code: |
+      # latest-available picks the newest installed runtime automatically:
+      steps:
+        - name: Run iOS tests
+          run: |
+            xcodebuild test \
+              -scheme MyApp \
+              -destination 'platform=iOS Simulator,name=iPhone 16,OS=latest-available'
+
+  - language: yaml
+    label: 'Discover installed simulator runtimes before running tests'
+    code: |
+      # Add a diagnostic step to see what runtimes are available:
+      steps:
+        - name: List installed simulator runtimes
+          run: xcrun simctl list runtimes
+
+        # Example output after April 2026:
+        # == Runtimes ==
+        # iOS 26.2 (26.2) - com.apple.CoreSimulator.SimRuntime.iOS-26-2
+        # iOS 26.4 (26.4) - com.apple.CoreSimulator.SimRuntime.iOS-26-4
+        # watchOS 26.2 ...
+        # (iOS 26.0 is NO LONGER listed)
+
+        - name: Run tests against iOS 26.4
+          run: |
+            xcodebuild test \
+              -scheme MyApp \
+              -destination 'platform=iOS Simulator,name=iPhone 16,OS=26.4'
+prevention:
+  - 'Never hardcode specific iOS/watchOS/tvOS simulator runtime version numbers in xcodebuild destination strings — use OS:latest-available or dynamically query installed runtimes.'
+  - 'Check the macOS runner image Readme before each Xcode GA update to verify which simulator runtime sets are installed: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md'
+  - 'Subscribe to runner-images announcements and PRs that add new Xcode GA versions — they always remove the oldest simulator runtime set.'
+  - 'If you need to test against a specific older runtime, use maxim-lobanov/setup-ios-simulator to download it on demand rather than relying on pre-installed runtimes.'
+docs:
+  - url: 'https://github.com/actions/runner-images/pull/13875'
+    label: 'runner-images PR #13875 — Xcode 26.4 GA: added 26.4 runtimes, removed 26.0.1 runtimes'
+  - url: 'https://github.com/actions/runner-images/issues/13853'
+    label: 'runner-images#13853 — macos-26-arm64 Xcode 26.4 RC missing iOS 26.4 simulator runtime'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md'
+    label: 'macOS 26 arm64 runner image Readme — installed simulators section'

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/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.129",
+  "version": "1.0.131",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",