@htekdev/actions-debugger 1.0.6 → 1.0.8

package/errors/caching-artifacts/cache-10gb-limit-eviction.yml

@@ -0,0 +1,135 @@
+id: caching-artifacts-011
+title: "Repository Cache Storage Limit (10 GB) — Silent Eviction Causes Cache Miss Spike"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - storage-limit
+  - eviction
+  - cache-miss
+  - actions/cache
+  - 10gb
+  - lru
+patterns:
+  - regex: "cache.*evict|evict.*cache"
+    flags: "i"
+  - regex: "cache size.*limit|limit.*cache size"
+    flags: "i"
+  - regex: "exceeds.*10.*GB|10.*GB.*limit"
+    flags: "i"
+  - regex: "cache.*storage.*limit.*exceeded"
+    flags: "i"
+error_messages:
+  - "Cache entry is too big. Maximum cache size is 10GB"
+  - "Warning: Cache size of XY GB (ZZZZ MB) is over the 10 GB limit, so some older caches will be removed"
+  - "Failed to save cache entry. Exiting with error: Cache storage quota has been reached for the current repository"
+root_cause: |
+  GitHub limits the total Actions cache storage per repository to **10 GB**. When the
+  10 GB limit is reached, GitHub automatically evicts the **least-recently-used (LRU)**
+  cache entries to make room for new ones. Additionally, cache entries that have not been
+  accessed in **7 days** are automatically deleted.
+
+  **This is a silent failure** because:
+  - Eviction happens asynchronously — the job that triggers eviction does not fail.
+  - The workflow that was relying on an evicted cache simply gets a cache miss on the
+    next run and reinstalls from scratch, adding minutes to build time.
+  - There is no notification, no warning in the workflow log, and no failed check.
+  - Engineers often diagnose this as a "flaky cache" without realizing the 10 GB limit
+    is being hit regularly.
+
+  **Common causes of limit exhaustion:**
+  1. **Matrix builds with many OS/version combinations** each storing large dependency
+     caches (node_modules, .cargo, ~/.gradle, etc.).
+  2. **Large monorepo caches** where the entire dependency tree exceeds 10 GB.
+  3. **Docker layer caches** stored via `actions/cache` for repeated builds.
+  4. **Accumulation without cleanup** — cache keys rotate on every dependency update
+     but old entries aren't explicitly purged.
+
+  **How to check current cache usage:**
+  Repository → Actions → Management → Caches (or via `gh cache list --repo owner/repo`).
+fix: |
+  Reduce total cache storage by improving cache key strategy and explicitly pruning old
+  cache entries.
+
+  **Immediate steps:**
+  1. Audit current cache usage with `gh cache list --repo owner/repo --sort size --order desc`
+  2. Delete oversized or stale entries with `gh cache delete <id> --repo owner/repo`
+  3. Review matrix build cache keys — large matrices with OS+version combinations
+     multiply cache storage proportionally.
+
+  **Structural fixes:**
+  - Use more specific cache keys to avoid storing redundant versions.
+  - Split large caches into smaller focused caches (dependencies vs. build outputs).
+  - Add a periodic workflow to prune old caches before the limit is reached.
+  - For Docker layer caches, consider using GitHub Container Registry or a dedicated
+    cache registry instead of Actions cache.
+fix_code:
+  - language: yaml
+    label: "Check cache usage and delete stale entries in a workflow"
+    code: |
+      jobs:
+        cleanup-caches:
+          runs-on: ubuntu-latest
+          steps:
+            - name: List and clean old caches
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                # List all caches sorted by last accessed time (oldest first)
+                gh cache list \
+                  --repo ${{ github.repository }} \
+                  --sort last-accessed \
+                  --order asc \
+                  --limit 100 \
+                  --json id,key,sizeInBytes,lastAccessedAt \
+                  | jq -r '.[] | "\(.id)\t\(.sizeInBytes)\t\(.lastAccessedAt)\t\(.key)"'
+  - language: yaml
+    label: "Prune caches older than N days using the Actions API"
+    code: |
+      jobs:
+        prune-caches:
+          runs-on: ubuntu-latest
+          permissions:
+            actions: write
+          steps:
+            - name: Delete caches not accessed in 5 days
+              env:
+                GH_TOKEN: ${{ github.token }}
+                REPO: ${{ github.repository }}
+              run: |
+                CUTOFF=$(date -d '5 days ago' --iso-8601=seconds)
+                gh api "repos/$REPO/actions/caches" \
+                  --paginate \
+                  --jq ".actions_caches[] | select(.last_accessed_at < \"$CUTOFF\") | .id" \
+                | xargs -I{} gh api --method DELETE "repos/$REPO/actions/caches/{}"
+  - language: yaml
+    label: "Optimize matrix builds to share a single cache entry"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: ['18', '20', '22']
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                # Share cache across Node versions — hash only package-lock.json
+                key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: npm-${{ runner.os }}-
+prevention:
+  - "Monitor total cache usage regularly with `gh cache list --repo owner/repo` or the GitHub UI (Actions → Caches) — set up an alert when approaching 8 GB."
+  - "Add a weekly scheduled workflow that prunes caches older than 5-7 days to stay well under the 10 GB limit."
+  - "Use `actions: write` permission and the REST API to manage caches programmatically as part of your CI housekeeping."
+  - "Design cache keys to be OS-specific but NOT dependency-version-specific where possible — this reduces the number of unique cache entries stored simultaneously."
+  - "For Docker layer caches, prefer GitHub Container Registry or an external caching service to avoid eating into the 10 GB Actions cache budget."
+  - "Check for cache key patterns that change too frequently (e.g., including `github.run_id`) — these create orphaned entries that accumulate until evicted."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy"
+    label: "GitHub Docs: Cache usage limits and eviction policy"
+  - url: "https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28"
+    label: "GitHub REST API: Actions cache endpoints"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache: Tips and workarounds"

package/errors/runner-environment/docker-29-compose-v2-40-breaking.yml

@@ -0,0 +1,144 @@
+id: runner-environment-031
+title: "Docker 29.1 + Compose 2.40.3 Runner Update Breaks Compose Commands"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-compose
+  - docker-29
+  - compose-v2
+  - ubuntu
+  - windows
+  - runner-image-update
+patterns:
+  - regex: "docker compose.*unknown flag|unknown flag.*docker compose"
+    flags: "i"
+  - regex: "docker-compose.*command not found|docker-compose.*deprecated"
+    flags: "i"
+  - regex: "compose.*unknown command|error.*compose.*not a docker command"
+    flags: "i"
+  - regex: "docker compose.*plugin.*not found|failed to get plugins"
+    flags: "i"
+error_messages:
+  - "docker-compose: command not found"
+  - "unknown flag: --compatibility"
+  - "unknown shorthand flag: 'f' in -f"
+  - "Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.25"
+  - "'docker compose' requires at least 1 argument"
+root_cause: |
+  On **February 9, 2026**, GitHub pushed an update to Ubuntu and Windows runner images
+  that bumped Docker Server and Client from 28.x to **29.1.*** and Docker Compose from
+  2.x to **2.40.3** (announced in actions/runner-images#13474).
+
+  For Ubuntu 24.04, the update was **rolled back** on February 20, 2026 due to multiple
+  reported issues (#13682, #13691, #13684) and is being re-evaluated (tracked in
+  #14105). The Windows runner update proceeded.
+
+  **Breaking changes in Docker Compose 2.40.x and Docker 29.x:**
+
+  1. **`docker-compose` v1 binary removed** — Many older workflows use the hyphenated
+     `docker-compose` command (Compose v1). As of Docker Compose v2, only the plugin
+     form `docker compose` (no hyphen) is installed. Workflows with
+     `run: docker-compose up -d` fail with `command not found`.
+
+  2. **`--compatibility` flag removed** — The `docker compose --compatibility` flag
+     (for mapping v2 configs to v2-compatible behavior) was removed in 2.40.x.
+     Workflows that use `docker compose --compatibility up` fail.
+
+  3. **API version minimums** — Docker 29 raises the minimum supported Docker daemon
+     API version, breaking some older base images in service containers that use the
+     Docker socket with old clients.
+
+  4. **`COMPOSE_DOCKER_CLI_BUILD` env var deprecated** — Setting
+     `COMPOSE_DOCKER_CLI_BUILD=1` no longer has any effect; BuildKit is always used.
+
+  5. **Docker 29.5 `CLONE_NEWTIME` private time namespaces** — Docker 29.5 (released
+     May 2026) enables private time namespaces by default on kernels ≥ 5.6, which
+     breaks Docker-socket-passthrough patterns used in Cloud Native Buildpacks (CNB)
+     lifecycle builds. Buildpack builds via `pack build` or Spring Boot's built-in
+     Buildpacks fail silently or with lifecycle container errors.
+fix: |
+  **For `docker-compose` → `docker compose` migration:**
+  Replace all `docker-compose` (hyphenated) invocations with `docker compose` (space).
+  This is the most common fix.
+
+  **For `--compatibility` flag removal:**
+  Remove the `--compatibility` flag. Docker Compose v2 handles modern compose file
+  formats natively without this flag.
+
+  **For CNB/Buildpack Docker socket passthrough (Docker 29.5+):**
+  Mount the Docker socket without private time namespaces by using
+  `--security-opt=no-new-privileges:false` or by setting
+  `DOCKER_HOST` to use a sidecar daemon.
+
+  **For pinning Docker version on self-hosted runners:**
+  Pin to Docker 28.x until your Compose files and build pipelines are validated against
+  29.x.
+fix_code:
+  - language: yaml
+    label: "Replace docker-compose (v1) with docker compose (v2 plugin)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ Old (docker-compose v1 — removed)
+            # - run: docker-compose up -d
+            # - run: docker-compose --compatibility up -d
+
+            # ✅ New (docker compose v2 plugin)
+            - name: Start services
+              run: docker compose up -d
+
+            - name: Run tests
+              run: docker compose exec app npm test
+
+            - name: Tear down
+              run: docker compose down
+  - language: yaml
+    label: "Verify Docker and Compose versions in workflow"
+    code: |
+      jobs:
+        debug:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check Docker version
+              run: |
+                docker version
+                docker compose version
+                # If docker-compose (v1) is needed, install it explicitly:
+                # pip install docker-compose
+  - language: yaml
+    label: "Pin Docker version for self-hosted runners sensitive to 29.x changes"
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          steps:
+            - name: Pin Docker to 28.x (if 29.x breaks your workflow)
+              run: |
+                sudo apt-get remove -y docker-ce docker-ce-cli
+                sudo apt-get install -y docker-ce=5:28.0.4-1~ubuntu.24.04~noble \
+                  docker-ce-cli=5:28.0.4-1~ubuntu.24.04~noble
+prevention:
+  - "Migrate from `docker-compose` (v1) to `docker compose` (v2 plugin) immediately —
+    v1 is no longer maintained and is removed in Docker 29.x images."
+  - "Remove `--compatibility` flags from all Compose invocations; the flag was
+    deprecated and is removed in Compose 2.40.x."
+  - "Subscribe to `actions/runner-images` announcements to get advance notice of
+    Docker version bumps before they land on hosted runners."
+  - "Pin Docker Compose file format version at `version: '3.8'` or later; v2 Compose
+    files have better compatibility with modern Compose plugin versions."
+  - "Test workflows in a local Docker 29.x environment before relying on them in CI
+    to catch API and behavioral differences early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13474"
+    label: "Announcement: Docker 29.1 + Compose 2.40.3 update (runner-images#13474)"
+  - url: "https://github.com/actions/runner-images/issues/14105"
+    label: "Tracking: Ubuntu Docker v29 rollback and re-attempt (runner-images#14105)"
+  - url: "https://docs.docker.com/compose/releases/migrate/"
+    label: "Docker Docs: Migrate from Compose v1 to v2"
+  - url: "https://docs.docker.com/engine/release-notes/29.1/"
+    label: "Docker Engine 29.1 release notes"

package/errors/runner-environment/node-20-toolcache-removal.yml

@@ -0,0 +1,134 @@
+id: runner-environment-029
+title: "Node.js 20 Removed from Runner Image Toolcache — Scripts Break Without setup-node"
+category: runner-environment
+severity: error
+tags:
+  - node
+  - nodejs
+  - toolcache
+  - node20
+  - node22
+  - setup-node
+  - eol
+patterns:
+  - regex: "node.*not found|node: command not found"
+    flags: "i"
+  - regex: "node.*version.*20.*not.*available|node 20.*removed"
+    flags: "i"
+  - regex: "required node.*20|node@20.*not installed"
+    flags: "i"
+  - regex: "engines.*node.*20.*not satisfied"
+    flags: "i"
+error_messages:
+  - "node: command not found"
+  - "The tool 'node' for version spec '20' was not found locally."
+  - "Couldn't resolve the package 'node' to a version matching '20'"
+  - "error engines: The engine \"node\" is incompatible with this module."
+root_cause: |
+  Node.js 20 reached **end-of-life on April 30, 2026**. Starting with runner image
+  releases on **May 18, 2026** (commit 249562679f on actions/runner-images), Node.js 20
+  was removed from the pre-installed toolcache on all runner images (Ubuntu, macOS,
+  Windows).
+
+  **What changed:**
+  - The default system `node` binary on all runner images changed from Node.js **20**
+    to Node.js **22** (Maintenance LTS).
+  - `node 20` is no longer available in the toolcache — `actions/setup-node` will
+    download it from the internet if explicitly requested, or fail if the network is
+    not available (self-hosted runners with restricted network access).
+  - Workflows that use `node` without `actions/setup-node` now get Node 22 by default.
+
+  **Three distinct breakage patterns:**
+
+  1. **Shell scripts calling `node script.js`** — these now run under Node 22, which
+     may break code that relied on Node 20 behavior (e.g., `fetch` API differences,
+     removed experimental APIs, `--openssl-legacy-provider` not available by default).
+
+  2. **`actions/setup-node` without version** — previously defaulted to node-version-
+     file lookup or the installed 20.x; now defaults to the latest LTS (22.x). Any
+     `package.json` `engines` field restricting to `>=20 <21` still works, but strict
+     `20.x` pins will now cause download overhead or failure.
+
+  3. **Self-hosted runners with restricted internet access** — if a workflow requests
+     `node-version: '20'` via `actions/setup-node` and the runner has no internet
+     access to download from nodejs.org, the setup step fails because 20 is no longer
+     in the local toolcache.
+
+  Note: This is distinct from the **action runtime migration** (Node 20 → Node 24 for
+  running JavaScript actions themselves, announced separately). This entry covers the
+  *pre-installed Node.js available to shell scripts*.
+fix: |
+  Update workflows to use Node.js 22 (current Maintenance LTS) or pin an explicit LTS
+  version via `actions/setup-node`.
+
+  **Option 1 — Explicit version pin (recommended for reproducibility):**
+  Add `actions/setup-node` with an explicit `node-version` or `node-version-file`.
+
+  **Option 2 — Use `.nvmrc` or `.node-version` file:**
+  Create a version file in the repo root and use `node-version-file` input.
+
+  **Option 3 — Accept Node 22:**
+  Test your application on Node 22 and update `package.json` `engines` accordingly.
+
+  **For self-hosted runners with no internet:**
+  Pre-install Node.js 22 in the runner's local toolcache directory and point
+  `AGENT_TOOLSDIRECTORY` to it.
+fix_code:
+  - language: yaml
+    label: "Pin explicit Node.js version via actions/setup-node"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'   # or '20' to keep on 20 (downloaded from web)
+                cache: 'npm'
+            - run: npm ci
+            - run: npm test
+  - language: yaml
+    label: "Use .nvmrc to declare Node version in the repo"
+    code: |
+      # .nvmrc (in repo root)
+      # 22
+
+      # workflow step
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: "Matrix build to verify compatibility across Node versions"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              node-version: ['20', '22', '24']
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node-version }}
+            - run: npm ci && npm test
+prevention:
+  - "Always use `actions/setup-node` with an explicit `node-version` or
+    `node-version-file` — never rely on the runner's pre-installed Node.js version."
+  - "Add a `.nvmrc` or `.node-version` file to your repository to pin Node.js version
+    for local dev, CI, and Vercel/Netlify deployments simultaneously."
+  - "Watch for Node.js EOL dates at https://github.com/nodejs/release#readme — plan
+    upgrades before the runner image drops the EOL version."
+  - "For self-hosted runners, maintain a local toolcache refresh process whenever a
+    new Node.js LTS is released or an old one reaches EOL."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14029"
+    label: "Announcement: Node.js 20 removal from runner images (runner-images#14029)"
+  - url: "https://github.com/nodejs/release#readme"
+    label: "Node.js Release Schedule — EOL dates"
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node — official action documentation"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/customizing-github-hosted-runners"
+    label: "GitHub Docs: Customizing GitHub-hosted runners"

package/errors/runner-environment/setup-python-cache-no-dependency-file.yml

@@ -0,0 +1,126 @@
+id: runner-environment-027
+title: "actions/setup-python cache Fails — No Dependency File Found for pip/poetry/pipenv"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - cache
+  - pip
+  - poetry
+  - pipenv
+  - cache-dependency-path
+  - requirements.txt
+  - pyproject.toml
+patterns:
+  - regex: "No file.*found for the supported package managers"
+    flags: "i"
+  - regex: "Error: No file in .* found for the supported package managers"
+    flags: "i"
+  - regex: "setup-python.*cache.*dependency.*not found"
+    flags: "i"
+  - regex: "dependencies were not found for the cache-dependency-path"
+    flags: "i"
+  - regex: "Could not find .* in .*requirements"
+    flags: "i"
+error_messages:
+  - "Error: No file in /home/runner/work/my-repo/my-repo found for the supported package managers (pip, pipenv, poetry), file patterns (requirements*.txt, Pipfile.lock, poetry.lock)"
+  - "Error: No file in /home/runner/work found for the supported package managers (pip), file patterns (requirements*.txt)"
+  - "dependencies were not found for the cache-dependency-path input"
+root_cause: |
+  When `actions/setup-python` is configured with `cache: 'pip'` (or `'poetry'` /
+  `'pipenv'`), it looks for a dependency lockfile to use as the cache key. The action
+  searches the repository for these file patterns:
+
+  | Cache type | File patterns searched                             |
+  |------------|---------------------------------------------------|
+  | `pip`      | `requirements*.txt`, `requirements/*.txt`         |
+  | `poetry`   | `poetry.lock`                                     |
+  | `pipenv`   | `Pipfile.lock`                                    |
+
+  If no matching file is found (either because the project uses a non-standard layout,
+  the file has a custom name, or the lockfile is gitignored), the action fails with this
+  error.
+
+  **Common causes:**
+  1. **Non-standard requirements file name**: `deps.txt`, `dev-requirements.txt` (outside
+     `requirements*.txt` glob), or stored in a subdirectory not matching the search path.
+  2. **pyproject.toml without poetry.lock**: Modern Python projects using `pyproject.toml`
+     with pip or flit don't generate a lockfile by default.
+  3. **Monorepo layout**: The requirements file is in a subdirectory (e.g.,
+     `backend/requirements.txt`) but the default search is from the repo root.
+  4. **Gitignored lockfiles**: `poetry.lock` or `Pipfile.lock` is in `.gitignore`, so
+     setup-python can't find it on the runner.
+
+  The `cache-dependency-path` input was added (actions/setup-python #361) to address
+  non-standard layouts, but is often overlooked in workflow templates.
+fix: |
+  Set the `cache-dependency-path` input to point to your actual dependency file, or
+  ensure the file follows the default naming convention.
+
+  **Option 1 (preferred):** Use `cache-dependency-path` to specify the exact path or glob.
+  **Option 2:** Rename your requirements file to match the default patterns (`requirements.txt`
+  or `requirements-*.txt`).
+  **Option 3:** If you don't need caching, remove `cache:` from the setup-python step entirely.
+  **Option 4 (pyproject.toml):** If using pip with pyproject.toml, create a
+  `requirements.txt` (or use `pip-compile`) to generate a lockfile for cache keying.
+fix_code:
+  - language: yaml
+    label: "Specify custom requirements file path with cache-dependency-path"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: |
+            backend/requirements.txt
+            backend/requirements-dev.txt
+  - language: yaml
+    label: "Use cache-dependency-path glob for monorepo with multiple requirements files"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: '**/requirements*.txt'
+  - language: yaml
+    label: "Poetry project with explicit cache-dependency-path"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'poetry'
+          cache-dependency-path: 'pyproject/poetry.lock'
+  - language: yaml
+    label: "pyproject.toml project using pip — generate a lockfile for cache keying"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          # No cache here — use actions/cache manually with hash of pyproject.toml
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+  - language: yaml
+    label: "Skip caching entirely when no lockfile exists"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          # Omit 'cache:' entirely — no caching, no failure
+      - run: pip install -r deps.txt
+prevention:
+  - "Always set `cache-dependency-path` explicitly rather than relying on the default file search — it makes the workflow self-documenting and prevents surprises on rename."
+  - "Commit `poetry.lock` and `Pipfile.lock` to version control — these files serve as both the reproducible install spec and the cache key."
+  - "In monorepos, use a glob pattern like `**/requirements*.txt` to match files across subdirectories."
+  - "If pyproject.toml is your only dependency file, use `actions/cache@v4` directly with `hashFiles('pyproject.toml')` instead of setup-python's built-in cache."
+  - "Pin to `actions/setup-python@v5` or later — older versions have different cache file discovery behavior."
+docs:
+  - url: "https://github.com/actions/setup-python?tab=readme-ov-file#caching-packages-dependencies"
+    label: "actions/setup-python: Caching packages dependencies"
+  - url: "https://github.com/actions/setup-python/issues/361"
+    label: "actions/setup-python #361: Support cache-dependency-paths outside the current directory"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs: Caching dependencies to speed up workflows"

package/errors/runner-environment/ubuntu-arm64-docker-not-preinstalled.yml

@@ -0,0 +1,137 @@
+id: runner-environment-030
+title: "Ubuntu ARM64 Runner Missing Docker — docker: command not found on arm64"
+category: runner-environment
+severity: error
+tags:
+  - arm64
+  - aarch64
+  - docker
+  - ubuntu
+  - partner-runner
+  - docker-buildx
+  - setup-buildx-action
+patterns:
+  - regex: "docker.*command not found|docker.*not found.*arm64"
+    flags: "i"
+  - regex: "docker/setup-buildx-action.*error|setup-buildx.*arm64.*fail"
+    flags: "i"
+  - regex: "Cannot connect to the Docker daemon|Is the docker daemon running"
+    flags: "i"
+  - regex: "Error: Unable to locate executable file: docker"
+    flags: "i"
+error_messages:
+  - "docker: command not found"
+  - "Error: Unable to locate executable file: docker"
+  - "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"
+  - "exec: \"docker\": executable file not found in $PATH"
+root_cause: |
+  GitHub-hosted **Ubuntu 24.04 ARM64** runner images (available via labels such as
+  `ubuntu-24.04-arm64`, `ubuntu-arm`, or partner runner images for ARM64) do **not**
+  have Docker pre-installed on `PATH`, despite the partner image README listing Docker
+  client and server versions.
+
+  This is a **documentation mismatch** affecting ARM64 runner users (actions/runner-
+  images#14051, created March 2026, still open as of May 2026):
+  - The `partner-runner-images` README lists Docker Client 28.0.4 and Docker Server
+    28.0.4 as installed software.
+  - In practice, `docker` is **not present on `PATH`** in these runners.
+  - The runner is identified as `Source: Partner` and `Base Image for Ubuntu Server
+    24.04`.
+
+  **Affected workflows:**
+  - Any step using `docker build`, `docker run`, `docker pull`, or `docker push`
+    directly in a `run:` block.
+  - `docker/setup-buildx-action@v3` fails because it cannot find the Docker CLI.
+  - Container-based jobs that use the host Docker socket.
+  - Multi-platform builds that need BuildKit on ARM64.
+
+  **x86-64 runners are not affected.** This is specific to ARM64 GitHub-hosted
+  runners using the partner image.
+
+  This is distinct from the `docker-buildx-not-setup.yml` entry (which covers x64
+  runners where Docker BuildKit is present but `buildx` is not configured).
+fix: |
+  Install Docker explicitly at the start of ARM64 workflow jobs, or use a Docker
+  action that handles installation automatically.
+
+  **Option 1 — Install Docker via the official convenience script (fastest):**
+  Run the Docker install script at the start of the job. This adds ~60 seconds to
+  job start time but ensures Docker is available.
+
+  **Option 2 — Use `docker/setup-buildx-action@v3` after Docker install:**
+  After installing Docker, `setup-buildx-action` can then install BuildKit buildx.
+
+  **Option 3 — Use a Docker-pre-installed large runner:**
+  If budget allows, use GitHub's x86-64 larger runners which have Docker pre-installed,
+  or a self-hosted ARM64 runner with Docker pre-configured.
+
+  **Option 4 — Use `runs-on: ubuntu-latest` (x86-64) instead of ARM64:**
+  If ARM64 is not strictly required, run on x86-64 which has Docker pre-installed.
+fix_code:
+  - language: yaml
+    label: "Install Docker on ARM64 runner before using it"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm64
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Docker
+              run: |
+                curl -fsSL https://get.docker.com -o get-docker.sh
+                sudo sh get-docker.sh
+                sudo usermod -aG docker $USER
+                sudo systemctl start docker
+                docker --version
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Build image
+              run: docker build -t myapp:latest .
+  - language: yaml
+    label: "Cross-platform build with explicit ARM64 Docker install"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - runner: ubuntu-latest
+                  platform: linux/amd64
+                - runner: ubuntu-24.04-arm64
+                  platform: linux/arm64
+                  install_docker: true
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install Docker (ARM64 only)
+              if: matrix.install_docker == true
+              run: |
+                curl -fsSL https://get.docker.com | sudo sh
+                sudo usermod -aG docker $USER
+                sudo systemctl enable --now docker
+
+            - name: Build for ${{ matrix.platform }}
+              run: docker build --platform ${{ matrix.platform }} -t myapp .
+prevention:
+  - "Before adding `runs-on: ubuntu-24.04-arm64` to a workflow that uses Docker,
+    verify Docker availability by running `docker --version` in a test job."
+  - "Check the current partner runner image README at
+    https://github.com/actions/partner-runner-images before relying on pre-installed
+    tooling on non-standard runner images."
+  - "Consider using self-hosted ARM64 runners with Docker pre-configured for
+    production workloads that depend on Docker on ARM64."
+  - "Track the open issue (actions/runner-images#14051) for when GitHub adds Docker
+    to ARM64 partner images natively."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14051"
+    label: "Issue: Ubuntu 24.04 ARM64 missing Docker (runner-images#14051)"
+  - url: "https://github.com/actions/partner-runner-images"
+    label: "actions/partner-runner-images — partner runner image definitions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "GitHub Docs: GitHub-hosted runner specifications"
+  - url: "https://docs.docker.com/engine/install/ubuntu/"
+    label: "Docker Docs: Install Docker Engine on Ubuntu"

package/errors/runner-environment/windows-2019-runner-retirement.yml

@@ -0,0 +1,100 @@
+id: runner-environment-028
+title: "windows-2019 Runner Retired — Jobs Fail with No Runner Found"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-2019
+  - runner-retirement
+  - deprecation
+  - runs-on
+  - migration
+patterns:
+  - regex: "No runner matching the requested labels.*windows-2019"
+    flags: "i"
+  - regex: "Could not find any runner matching.*windows-2019"
+    flags: "i"
+  - regex: "windows-2019.*is no longer supported"
+    flags: "i"
+  - regex: "windows-2019.*deprecated.*unsupported"
+    flags: "i"
+error_messages:
+  - "No runner matching the requested labels was found: windows-2019"
+  - "Could not find any runner matching the requested labels: [windows-2019]"
+  - "This request was automatically failed because 'windows-2019' is no longer available."
+root_cause: |
+  GitHub retired the `windows-2019` runner image on **June 30, 2025** following the
+  GitHub Actions N-1 OS support policy (only the latest two major versions of each OS
+  are hosted).
+
+  **Timeline:**
+  - **2025-04-15**: Deprecation announcement (actions/runner-images#12045)
+  - **2025-06-01**: Deprecation begins — longer queue times during peak hours
+  - **Between June 1–30**: GitHub temporarily fails jobs using `windows-2019` to raise
+    awareness in advance of the hard removal
+  - **2025-06-30**: `windows-2019` fully unsupported — all jobs using this label fail
+
+  Workflows that explicitly specify `runs-on: windows-2019` (or any combination like
+  `[self-hosted, windows-2019]` on non-self-hosted runners) will fail immediately after
+  the retirement date. Workflows that used `windows-latest` were not affected since
+  `windows-latest` already pointed to `windows-2022`.
+
+  The replacement is `windows-2022` (already the current `windows-latest` at time of
+  retirement) or `windows-2025` (Windows Server 2025 image).
+fix: |
+  Update all `runs-on` references from `windows-2019` to `windows-2022` or
+  `windows-2025` (or use `windows-latest`).
+
+  **Migration path:**
+  - `windows-2019` → `windows-2022` (minimal change, widely compatible)
+  - `windows-2019` → `windows-2025` (latest; check for VS 2026 path changes if using
+    hardcoded MSVC paths)
+  - `windows-2019` → `windows-latest` (tracks latest, reduces future manual migrations)
+
+  **Before migrating**, verify that your workflow does not depend on Windows Server 2019
+  -specific behavior such as:
+  - VS 2019 toolchain at `C:\Program Files (x86)\Microsoft Visual Studio\2019\`
+  - Older .NET Framework SDK versions not present on 2022 or 2025 images
+  - Windows Server 2019-specific APIs or registry keys
+fix_code:
+  - language: yaml
+    label: "Replace windows-2019 with windows-2022"
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: windows-2019
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: msbuild MyApp.sln /p:Configuration=Release
+  - language: yaml
+    label: "Use windows-latest to avoid future manual migrations"
+    code: |
+      jobs:
+        build:
+          # windows-latest currently points to windows-2025 (as of June 2026)
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: bash
+    label: "Audit all workflows for windows-2019 references"
+    code: |
+      # Find all workflow files using windows-2019
+      grep -r "windows-2019" .github/workflows/
+prevention:
+  - "Use `windows-latest` instead of pinned OS versions unless you have a specific
+    reason to pin. This avoids retirement failures entirely."
+  - "Subscribe to the `actions/runner-images` repository announcements to receive
+    deprecation notices before they become hard failures."
+  - "When you must pin an OS version, add a calendar reminder or Renovate/Dependabot
+    rule to review the pin when the N-1 policy applies."
+  - "Run a periodic repository search for retired runner labels:
+    `grep -r 'windows-2019\\|ubuntu-20.04\\|macos-12' .github/workflows/`"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12045"
+    label: "Announcement: Windows 2019 deprecation and retirement (runner-images#12045)"
+  - url: "https://github.blog/changelog/2025-04-15-upcoming-breaking-changes-and-releases-for-github-actions/"
+    label: "GitHub Changelog: Windows Server 2019 is closing down"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs: Supported GitHub-hosted runners"

package/errors/triggers/merge-group-trigger-missing.yml

@@ -0,0 +1,122 @@
+id: triggers-007
+title: "merge_group Trigger Missing — Required Checks Never Run in Merge Queue"
+category: triggers
+severity: silent-failure
+tags:
+  - merge_group
+  - merge-queue
+  - required-checks
+  - branch-protection
+  - triggers
+  - pull_request
+patterns:
+  - regex: "merge_group"
+    flags: "i"
+  - regex: "Expected.*Waiting.*merge queue"
+    flags: "i"
+  - regex: "merge queue.*required.*status check.*waiting"
+    flags: "i"
+error_messages:
+  - "Required check 'CI' is expected — Waiting"
+  - "All checks have passed except those that are waiting for merge queue"
+  - "The merge queue is waiting for the required check to pass"
+root_cause: |
+  GitHub's merge queue (enabled via branch protection rules → "Require merge queue")
+  creates a `merge_group` event when a PR is added to the queue. This event is distinct
+  from `pull_request` and `push` — a workflow must explicitly declare `on: merge_group:`
+  to receive it.
+
+  When a workflow is required by branch protection but does NOT include `merge_group`
+  as a trigger, the merge queue adds the PR to a temporary merge group branch (format:
+  `gh-readonly-queue/{base}/{pr-number}`) but the required workflow **never starts**.
+  GitHub shows the required check as "Expected — Waiting" indefinitely, and the PR
+  cannot merge.
+
+  **Why this is subtle:**
+  - The workflow runs fine for normal `pull_request` events (dev branch → PR, all checks
+    pass).
+  - The failure only manifests once the PR is actually added to the merge queue.
+  - The "Waiting" status in the merge queue looks different from a failed check, making
+    it unclear that the workflow trigger is misconfigured.
+
+  **The merge_group event payload** is slightly different from `pull_request`:
+  - `github.event.merge_group.base_ref` — the base branch
+  - `github.event.merge_group.head_sha` — the merged commit SHA to test
+  - `github.event.merge_group.head_ref` — the temporary merge branch name
+fix: |
+  Add `merge_group:` to the `on:` block of every workflow that is listed as a required
+  status check for merge queue-protected branches.
+
+  **Important:** `merge_group` does NOT automatically run `pull_request` workflows — it
+  is a completely separate event type. You must add it explicitly.
+
+  If your workflow has conditions that reference `github.event_name == 'pull_request'`,
+  update those conditions to also allow `merge_group` events, or restructure them to
+  check `github.event.pull_request || github.event.merge_group`.
+fix_code:
+  - language: yaml
+    label: "Add merge_group trigger to an existing CI workflow"
+    code: |
+      on:
+        pull_request:
+          branches: [main, develop]
+        merge_group:          # <-- Add this to receive merge queue events
+          types: [checks_requested]
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: npm test
+  - language: yaml
+    label: "Conditional logic that handles both pull_request and merge_group"
+    code: |
+      on:
+        pull_request:
+        merge_group:
+          types: [checks_requested]
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Access the base SHA correctly for both event types
+            - name: Get base SHA
+              id: base
+              run: |
+                if [ "${{ github.event_name }}" = "merge_group" ]; then
+                  echo "sha=${{ github.event.merge_group.base_sha }}" >> $GITHUB_OUTPUT
+                else
+                  echo "sha=${{ github.event.pull_request.base.sha }}" >> $GITHUB_OUTPUT
+                fi
+  - language: yaml
+    label: "Reusable workflow that supports merge_group via workflow_call"
+    code: |
+      # In the caller workflow:
+      on:
+        pull_request:
+        merge_group:
+          types: [checks_requested]
+
+      jobs:
+        ci:
+          uses: ./.github/workflows/ci-reusable.yml
+          with:
+            ref: ${{ github.event.pull_request.head.sha || github.event.merge_group.head_sha }}
+prevention:
+  - "When enabling merge queue on a branch protection rule, immediately check that every required workflow has `merge_group` in its `on:` triggers."
+  - "Add a repository-level workflow audit that lists all required status checks and verifies each has a matching `merge_group` trigger."
+  - "Test the merge queue setup by creating a test PR and attempting to add it to the queue — if checks show 'Waiting', add the trigger."
+  - "Third-party Actions and path-filter actions (dorny/paths-filter, tj-actions/changed-files) may need explicit `merge_group` support — check their changelogs."
+  - "GitHub's documentation now includes a merge queue section — review it when enabling the feature in your organization."
+docs:
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue"
+    label: "GitHub Docs: Managing a merge queue"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group"
+    label: "GitHub Actions: merge_group event trigger"
+  - url: "https://github.blog/changelog/2023-02-08-pull-request-merge-queue-public-beta/"
+    label: "GitHub Changelog: Pull request merge queue public beta (Feb 2023)"

package/errors/yaml-syntax/set-output-deprecated-commands.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-015
+title: "Deprecated ::set-output:: / ::save-state:: / ::add-path:: Workflow Commands"
+category: yaml-syntax
+severity: warning
+tags:
+  - set-output
+  - save-state
+  - add-path
+  - deprecated
+  - GITHUB_OUTPUT
+  - GITHUB_ENV
+  - GITHUB_PATH
+  - workflow-commands
+patterns:
+  - regex: "The `set-output` command is deprecated"
+    flags: "i"
+  - regex: "The `save-state` command is deprecated"
+    flags: "i"
+  - regex: "The `set-env` command is disabled"
+    flags: "i"
+  - regex: "::set-output name="
+    flags: ""
+  - regex: "::save-state name="
+    flags: ""
+  - regex: "::add-path::"
+    flags: ""
+  - regex: "workflow commands.*deprecated.*will be disabled"
+    flags: "i"
+error_messages:
+  - "Warning: The `set-output` command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter"
+  - "Warning: The `save-state` command is deprecated and will be disabled soon. Please upgrade to using Environment Files."
+  - "Error: The `set-env` command is disabled. Please upgrade to using Environment Files."
+  - "Error: The `add-path` command is disabled. Please upgrade to using Environment Files."
+root_cause: |
+  GitHub Actions introduced a new Environment Files mechanism in 2020 to replace the
+  older `echo "::command::"` workflow commands. The old commands were deprecated in
+  October 2022 (security advisory: injection attacks could hijack `::set-output::` via
+  untrusted log output) and disabled shortly after.
+
+  **Deprecated commands and their replacements:**
+  | Old command                         | Replacement                                    |
+  |-------------------------------------|------------------------------------------------|
+  | `echo "::set-output name=K::V"`     | `echo "K=V" >> $GITHUB_OUTPUT`                 |
+  | `echo "::save-state name=K::V"`     | `echo "K=V" >> $GITHUB_STATE`                  |
+  | `echo "::set-env name=K::V"`        | `echo "K=V" >> $GITHUB_ENV`                    |
+  | `echo "::add-path::PATH"`           | `echo "PATH" >> $GITHUB_PATH`                  |
+
+  These commands still appear in:
+  - Third-party GitHub Actions that haven't been updated to a newer major version
+  - Scripts copied from old Stack Overflow answers or blog posts
+  - Custom scripts that use the `::set-output::` form directly
+  - Older composite actions where steps use `echo "::set-output name=result::$value"`
+
+  When the runner encounters these commands, it emits a deprecation warning. If the
+  commands are later hard-disabled for a repository (or for a specific runner version),
+  the output variable is simply never set — creating a silent downstream failure.
+fix: |
+  Replace all deprecated `::command::` syntax with the Environment Files equivalents
+  in your workflow YAML, composite action scripts, and any shell scripts that produce
+  outputs or modify the environment.
+
+  **Key rules:**
+  - `GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_STATE`, `GITHUB_PATH` are all file paths
+    that are set as environment variables by the runner.
+  - Append to these files — never overwrite them (`>>` not `>`).
+  - For multiline values, use the heredoc delimiter syntax (see fix_code below).
+  - On Windows (PowerShell), use `"K=V" | Out-File -FilePath $env:GITHUB_OUTPUT -Append`
+    or simply `echo "K=V" >> $env:GITHUB_OUTPUT` (cmd-style append works in pwsh too).
+fix_code:
+  - language: yaml
+    label: "Replace ::set-output:: with GITHUB_OUTPUT (bash)"
+    code: |
+      - name: Set output (modern)
+        id: my-step
+        run: |
+          # Old (deprecated):
+          # echo "::set-output name=version::1.2.3"
+
+          # New (use environment file):
+          echo "version=1.2.3" >> $GITHUB_OUTPUT
+
+      - name: Use output downstream
+        run: echo "Version is ${{ steps.my-step.outputs.version }}"
+  - language: yaml
+    label: "Replace ::set-output:: with GITHUB_OUTPUT (PowerShell)"
+    code: |
+      - name: Set output (PowerShell modern)
+        id: my-step
+        shell: pwsh
+        run: |
+          # Old (deprecated):
+          # Write-Output "::set-output name=version::1.2.3"
+
+          # New:
+          "version=1.2.3" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+  - language: yaml
+    label: "Replace ::save-state:: with GITHUB_STATE"
+    code: |
+      - name: Save state in pre step
+        run: echo "cleanup_token=${{ secrets.TOKEN }}" >> $GITHUB_STATE
+
+      - name: Read state in post step
+        run: echo "Token was $STATE_CLEANUP_TOKEN"
+        # State values are exposed as STATE_<NAME> environment variables
+  - language: yaml
+    label: "Multiline output value with heredoc delimiter"
+    code: |
+      - name: Set multiline output
+        id: changelog
+        run: |
+          EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
+          echo "notes<<$EOF" >> $GITHUB_OUTPUT
+          echo "Line 1 of release notes" >> $GITHUB_OUTPUT
+          echo "Line 2 of release notes" >> $GITHUB_OUTPUT
+          echo "$EOF" >> $GITHUB_OUTPUT
+prevention:
+  - "Audit all workflows and composite actions for `::set-output::`, `::save-state::`, `::set-env::`, and `::add-path::` patterns before they become hard failures."
+  - "Add a CI lint step using `grep -r '::set-output' .github/` to catch regressions."
+  - "When using third-party Actions, pin to a version tag that uses the modern file-based outputs — check the action's CHANGELOG for 'GITHUB_OUTPUT migration'."
+  - "For cross-platform workflows, test the `$GITHUB_OUTPUT` / `$env:GITHUB_OUTPUT` equivalence — both work on ubuntu/macos/windows runners."
+  - "Enable the 'Deprecation warnings as errors' setting in your organization's Actions policy to catch deprecated commands in CI before they silently fail."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter"
+    label: "GitHub Actions: Setting an output parameter (Environment Files)"
+  - url: "https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/"
+    label: "GitHub Changelog: Deprecating save-state and set-output commands (Oct 2022)"
+  - url: "https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/"
+    label: "GitHub Changelog: Deprecating set-env and add-path commands (Oct 2020)"
+  - url: "https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections"
+    label: "Security hardening: Understanding the risk of script injections"

package/package.json

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