@htekdev/actions-debugger 1.0.113 → 1.0.115

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

@@ -0,0 +1,97 @@
+id: permissions-auth-065
+title: "PAT Not SSO-Authorized for SAML SSO Organization — Checkout Returns 'Not Found' Despite Valid Token"
+category: permissions-auth
+severity: error
+tags:
+  - pat
+  - sso
+  - saml
+  - enterprise
+  - checkout
+  - not-found
+  - authentication
+patterns:
+  - regex: 'Not Found.*docs\.github\.com/rest/repos/repos'
+    flags: i
+  - regex: 'Retrieving the default branch name\s+Not Found'
+    flags: i
+  - regex: 'Waiting \d+ seconds before trying again\s+Retrieving the default branch name\s+Not Found'
+    flags: i
+error_messages:
+  - "Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+  - "Retrieving the default branch name"
+  - "Error: Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+root_cause: |
+  GitHub organizations that enforce SAML SSO require Personal Access Tokens (PATs) to be
+  explicitly authorized for that organization before they can access any organization resources
+  — regardless of the token's scopes. A PAT with `repo` (or even `admin:org`) scope is
+  insufficient on its own inside an SSO-enforced organization.
+
+  When an unauthorized PAT tries to access the repository metadata endpoint
+  (`GET /repos/{owner}/{repo}`), GitHub returns HTTP 404 "Not Found" instead of 401 or 403.
+  This is intentional — SSO-unauthorized access is treated as if the resource does not exist,
+  preventing information leakage. The result is a deeply confusing error because:
+  1. The repository exists and the PAT owner has access (confirmed via browser with SSO session)
+  2. The error says "Not Found" not "Unauthorized" or "SSO authorization required"
+  3. The checkout action retries with a 19-second back-off before finally failing
+
+  This affects `actions/checkout` with `token:` set to a PAT, any `gh api` or `curl` call
+  using the PAT, and any third-party action that uses a PAT to access the organization.
+fix: |
+  Authorize the PAT for the SAML SSO organization in GitHub Developer Settings:
+
+  1. Go to GitHub.com → Your profile → Settings → Developer settings
+  2. Select "Personal access tokens" → find the affected PAT
+  3. Click "Configure SSO" next to the token
+  4. Click "Authorize" next to the organization name
+  5. Complete the SSO authorization flow
+
+  After authorizing, the PAT can access organization resources and the checkout succeeds.
+
+  Alternative: Use a GitHub App installation token instead of a PAT. App tokens are not
+  subject to the SSO authorization requirement — the app must be installed in the organization
+  (which requires an admin to approve), but once installed its tokens work without per-token
+  SSO authorization.
+fix_code:
+  - language: yaml
+    label: "Checkout using a PAT that has been SSO-authorized for the org"
+    code: |
+      # First: authorize the PAT for the org in GitHub Developer Settings → Configure SSO
+      # Then use it in the workflow:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                repository: my-org/private-repo
+                token: ${{ secrets.GH_PAT }}   # must be SSO-authorized for my-org
+  - language: yaml
+    label: "Use a GitHub App token to avoid SSO authorization requirement"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/create-github-app-token@v1
+              id: app-token
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: my-org
+            - uses: actions/checkout@v4
+              with:
+                repository: my-org/private-repo
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "After creating a PAT for use in an SSO-enforced organization, always click 'Configure SSO' and authorize it for every relevant organization immediately"
+  - "Prefer GitHub App installation tokens over PATs for organization-scoped workflows — Apps do not require per-token SSO authorization"
+  - "Document the SSO authorization requirement in your team's GitHub Actions onboarding guide — it is not surfaced in the error message"
+  - "When troubleshooting a 'Not Found' error with a PAT that has correct scopes, check SSO authorization before assuming the repo path or scopes are wrong"
+docs:
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on"
+    label: "GitHub Docs: Authorizing a PAT for use with SAML SSO"
+  - url: "https://stackoverflow.com/questions/79874764/github-actions-checkout-fails-with-not-found-error-for-sso-protected-enterpris"
+    label: "Stack Overflow — GitHub Actions checkout fails with Not Found for SSO-protected enterprise repo (Jan 2026)"
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/rest/authentication/authenticating-to-the-rest-api"
+    label: "GitHub Docs: Authenticating to the REST API (SSO requirements)"

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

@@ -0,0 +1,129 @@
+id: permissions-auth-066
+title: "AWS IAM OIDC Trust Policy Pins Reusable Workflow to Version Tag — Breaks on Called Action Major Version Upgrade"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - aws
+  - iam
+  - reusable-workflow
+  - job_workflow_ref
+  - version-tag
+  - trust-policy
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: i
+  - regex: 'Could not assume role with OIDC'
+    flags: i
+  - regex: 'AccessDenied.*AssumeRoleWithWebIdentity'
+    flags: i
+error_messages:
+  - "Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "An error occurred (AccessDenied) when calling the AssumeRoleWithWebIdentity operation: Not authorized to perform sts:AssumeRoleWithWebIdentity"
+root_cause: |
+  When a reusable workflow is called at a specific version tag (e.g.,
+  `uses: org/lib/.github/workflows/deploy.yml@v2`), GitHub's OIDC token embeds the called
+  workflow's ref in the `sub` claim as `job_workflow_ref`:
+
+    repo:ORG/CALLER:job_workflow_ref:org/lib/.github/workflows/deploy.yml@refs/tags/v2.1.0
+
+  An AWS IAM trust policy that uses a `StringLike` condition pinned to a specific version
+  pattern such as `@refs/tags/v2*` accepts this token. However, when the caller upgrades
+  the called action from `@v2` to `@v3`, the OIDC token `sub` claim changes to:
+
+    repo:ORG/CALLER:job_workflow_ref:org/lib/.github/workflows/deploy.yml@refs/tags/v3.0.0
+
+  The `@refs/tags/v2*` condition no longer matches `@refs/tags/v3.0.0`, so AWS STS rejects
+  the `AssumeRoleWithWebIdentity` call with AccessDenied. The error message is identical to
+  any other OIDC trust policy mismatch — nothing in the error output reveals that the version
+  tag in the `job_workflow_ref` claim is the cause.
+
+  This is distinct from the ref→job_workflow_ref format change (permissions-auth-044) which
+  occurs when a direct job is refactored into a reusable workflow. Here, the `job_workflow_ref`
+  format is already in use and working — it breaks silently only after a version upgrade.
+fix: |
+  Update the AWS IAM trust policy `StringLike` condition to accept any version of the called
+  workflow, not a pinned version pattern. Use a wildcard that matches across versions.
+
+  Option A (wildcard on the version suffix — recommended):
+    Replace `@refs/tags/v2*` with `@*` or use a broader pattern that includes the full path
+    before the version, such as:
+    `"repo:ORG/CALLER:job_workflow_ref:org/lib/.github/workflows/deploy.yml@*"`
+
+  Option B (OIDC subject claim customization):
+    Use GitHub's OIDC subject claim customization (repo Settings → Actions → General → OIDC
+    subject claims) to define a custom sub template that excludes the `job_workflow_ref` field
+    or removes the version portion. Then update the trust policy to match the customized sub.
+
+  Option C (accept both old and new versions):
+    Add both version patterns to the IAM trust policy during a transition window:
+    `StringLike: ["...deploy.yml@refs/tags/v2*", "...deploy.yml@refs/tags/v3*"]`
+    Remove the old pattern after all callers have upgraded.
+fix_code:
+  - language: json
+    label: "AWS IAM trust policy — version-agnostic StringLike condition (recommended)"
+    code: |
+      {
+        "Version": "2012-10-17",
+        "Statement": [
+          {
+            "Effect": "Allow",
+            "Principal": {
+              "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
+            },
+            "Action": "sts:AssumeRoleWithWebIdentity",
+            "Condition": {
+              "StringEquals": {
+                "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+              },
+              "StringLike": {
+                "token.actions.githubusercontent.com:sub": "repo:ORG/CALLER:job_workflow_ref:org/lib/.github/workflows/deploy.yml@*"
+              }
+            }
+          }
+        ]
+      }
+  - language: json
+    label: "Multi-version transition — accept both v2 and v3 during upgrade"
+    code: |
+      {
+        "Condition": {
+          "StringEquals": {
+            "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+          },
+          "StringLike": {
+            "token.actions.githubusercontent.com:sub": [
+              "repo:ORG/CALLER:job_workflow_ref:org/lib/.github/workflows/deploy.yml@refs/tags/v2*",
+              "repo:ORG/CALLER:job_workflow_ref:org/lib/.github/workflows/deploy.yml@refs/tags/v3*"
+            ]
+          }
+        }
+      }
+  - language: yaml
+    label: "How to decode the actual sub claim from a failing run"
+    code: |
+      # Add this step before configure-aws-credentials to log the actual sub claim
+      - name: Debug OIDC subject claim
+        id: debug-oidc
+        run: |
+          token=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+            "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=sts.amazonaws.com" | jq -r '.value')
+          echo "$token" | cut -d. -f2 | base64 -d 2>/dev/null | jq '.sub'
+        env:
+          ACTIONS_ID_TOKEN_REQUEST_TOKEN: ${{ env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }}
+          ACTIONS_ID_TOKEN_REQUEST_URL: ${{ env.ACTIONS_ID_TOKEN_REQUEST_URL }}
+prevention:
+  - "Use version-agnostic wildcards in IAM trust policy StringLike conditions (e.g., `@*` suffix) unless the policy intentionally restricts to a specific version"
+  - "Treat IAM OIDC trust policies as part of the release checklist — whenever a reusable workflow's major version is bumped, update the trust policy before merging callers"
+  - "Use GitHub OIDC subject claim customization to remove the version from the sub claim if version-agnostic trust is always preferred"
+  - "Document the expected sub claim format in the reusable workflow README alongside the required IAM trust policy pattern"
+  - "Run the sub-claim debug step in a dry-run workflow before updating the IAM trust policy to confirm the exact new sub value"
+docs:
+  - url: "https://github.com/aws-actions/configure-aws-credentials/issues/1707"
+    label: "aws-actions/configure-aws-credentials#1707 — OIDC AssumeRole fails after action version upgrade"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows"
+    label: "GitHub Docs: Using OIDC with reusable workflows"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository"
+    label: "GitHub Docs: Customizing OIDC subject claims"
+  - url: "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html"
+    label: "AWS Docs: IAM OIDC identity providers"

package/errors/permissions-auth/upload-code-coverage-missing-code-quality-write-permission.yml

@@ -0,0 +1,94 @@
+id: permissions-auth-068
+title: 'upload-code-coverage action fails with 403 — missing code-quality:write permission'
+category: permissions-auth
+severity: error
+tags:
+  - permissions
+  - code-quality
+  - upload-code-coverage
+  - github-token
+  - 403
+  - fine-grained
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'Upload failed.*403|HTTP 403.*code.coverage|code.coverage.*403'
+    flags: 'i'
+  - regex: 'code-quality.*write|code_quality.*write'
+    flags: 'i'
+error_messages:
+  - '{"message":"Resource not accessible by integration","documentation_url":"https://docs.github.com/rest"}'
+  - 'Error: Upload failed: HTTP 403 Forbidden'
+  - 'HTTP Status: 403'
+root_cause: |
+  GitHub's code coverage upload API (introduced May 2026 as part of Code Quality for
+  pull requests) requires the new fine-grained permission `code-quality:write` on the
+  calling token. The default GITHUB_TOKEN in GitHub Actions workflows has this permission
+  set to `none` unless explicitly granted.
+
+  When `actions/upload-code-coverage` calls the coverage upload API without this
+  permission, GitHub returns HTTP 403 "Resource not accessible by integration". Because
+  `code-quality:write` is a newly introduced permission class (not present in older
+  workflow permission schemas), developers familiar with the standard permissions
+  (contents, issues, pull-requests, etc.) don't know to add it.
+
+  This affects all workflows that do not specify `permissions:` at all (which defaults to
+  `read-all` — but `code-quality` is still `none` for new permissions), as well as
+  workflows that explicitly set `permissions: {}` or use a restrictive block.
+fix: |
+  Add `code-quality: write` to the `permissions` block of the job that runs
+  `actions/upload-code-coverage`. This grants the GITHUB_TOKEN the required scope to
+  call the code coverage upload API.
+
+  Note: `code-quality:` is a job-level permission. It cannot be set as a global
+  `GITHUB_TOKEN` permission through repository settings — it must be declared in the
+  workflow YAML per-job.
+fix_code:
+  - language: yaml
+    label: 'Add code-quality:write to the coverage upload job'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            code-quality: write    # Required for upload-code-coverage
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests and generate coverage
+              run: pytest --cov=src --cov-report=xml
+
+            - name: Upload code coverage
+              uses: actions/upload-code-coverage@v1
+              with:
+                file: coverage.xml
+                language: Python
+  - language: yaml
+    label: 'Minimal permissions block if no others are needed'
+    code: |
+      jobs:
+        coverage:
+          runs-on: ubuntu-latest
+          permissions:
+            code-quality: write
+          steps:
+            - uses: actions/upload-code-coverage@v1
+              with:
+                file: cobertura.xml
+                language: Java
+                label: code-coverage/jacoco
+prevention:
+  - "Whenever you add actions/upload-code-coverage to a workflow, immediately add `code-quality: write` to the job's permissions block."
+  - "Use a linter or policy-as-code tool (e.g., Poutine, StepSecurity) that validates required permissions against known action requirements."
+  - "If your org uses required permissions: {} at the workflow level for security hardening, remember that code-quality: write must still be declared per-job."
+  - "Check the GitHub Changelog periodically — new actions introduce new permission classes that aren't reflected in older documentation or IDE auto-complete."
+docs:
+  - url: 'https://github.blog/changelog/2026-05-26-code-coverage-in-pull-requests-is-now-in-public-preview/'
+    label: 'GitHub Changelog: Code coverage in pull requests (May 26, 2026)'
+  - url: 'https://github.com/actions/upload-code-coverage'
+    label: 'actions/upload-code-coverage repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'Controlling permissions for GITHUB_TOKEN'
+  - url: 'https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository'
+    label: 'GitHub Actions permissions documentation'

package/errors/runner-environment/arc-kubernetes-checkout-circular-json-container-hook.yml

@@ -0,0 +1,101 @@
+id: runner-environment-189
+title: 'ARC Kubernetes container hook fails with "Converting circular structure to JSON" during checkout'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - kubernetes
+  - container-hooks
+  - checkout
+  - circular-json
+  - self-hosted
+  - custom-container
+patterns:
+  - regex: 'Converting circular structure to JSON'
+    flags: 'i'
+  - regex: 'starting at object with constructor .ClientRequest.'
+    flags: 'i'
+  - regex: 'Executing the custom container implementation failed'
+    flags: 'i'
+  - regex: 'property .socket. -> object with constructor .TLSSocket.'
+    flags: 'i'
+error_messages:
+  - "TypeError: Converting circular structure to JSON\n    --> starting at object with constructor 'ClientRequest'\n    |     property 'socket' -> object with constructor 'TLSSocket'\n    --- property '_httpMessage' closes the circle"
+  - "Error: Executing the custom container implementation failed. Please contact your self hosted runner administrator."
+  - "Error: Process completed with exit code 1."
+root_cause: |
+  Actions Runner Controller (ARC) on Kubernetes uses Node.js container-hooks to manage
+  the lifecycle of job container pods. During container startup, ARC makes HTTP requests
+  to the Kubernetes API server to create or wait for pods. When a network request fails
+  mid-connection — due to Kubernetes API server latency, pod scheduling delays, or transient
+  network errors — the error handler in the container hook attempts to serialize the failing
+  Node.js http.ClientRequest object into JSON for logging or error reporting.
+
+  Node.js http.ClientRequest objects contain circular references:
+    ClientRequest → socket (TLSSocket) → _httpMessage → ClientRequest
+
+  JSON.stringify() cannot handle circular structures and throws:
+    "TypeError: Converting circular structure to JSON"
+
+  This error surfaces during the checkout step (or another early step) because the container
+  hook failure terminates the entire job. The error is not in actions/checkout itself — it is
+  in the ARC container-hooks layer executing underneath. The message
+  "Executing the custom container implementation failed" confirms the failure is in the
+  container hook, not the action code.
+
+  This is most commonly triggered by:
+  - Kubernetes API server under high load (slow pod scheduling acknowledgement)
+  - ARC container-hooks < v0.8.1 which lacks circular-reference guarding in error serialization
+  - Network timeouts between ARC runner pod and Kubernetes API during container create
+  - Combined ARC v2.332.0 + container-hooks v0.8.0 regression (see actions/runner#4302)
+fix: |
+  Upgrade ARC and container-hooks to versions that guard against circular reference
+  serialization. The actions/runner-controller v0.9.x chart pins container-hooks
+  v0.8.1+ which patches the circular JSON error.
+
+  If on ARC v2.332.0, also upgrade the runner image tag — that release combined a
+  base image change (Ubuntu 22.04 → 24.04) with a container-hooks version that
+  had this regression.
+
+  As a diagnostic step, check if the Kubernetes API server is under pressure — slow
+  pod acknowledgements cause the HTTP client to timeout in ways that expose this code path.
+fix_code:
+  - language: yaml
+    label: 'Pin ARC to a release with container-hooks v0.8.1+ fix'
+    code: |
+      # In your ARC AutoscalingRunnerSet Helm values:
+      # Upgrade to controller + runner image that includes container-hooks >= v0.8.1
+      # Check releases at https://github.com/actions/actions-runner-controller/releases
+      template:
+        spec:
+          containers:
+            - name: runner
+              # Use a runner image tag that ships container-hooks >= v0.8.1
+              image: ghcr.io/actions/actions-runner:latest
+  - language: yaml
+    label: 'Increase pod startup timeout to reduce API server pressure race'
+    code: |
+      # helm values — increase pod startup grace period to reduce
+      # Kubernetes API timeout racing against container hook
+      template:
+        spec:
+          terminationGracePeriodSeconds: 3600
+          containers:
+            - name: runner
+              resources:
+                requests:
+                  memory: '2Gi'
+                  cpu: '500m'
+prevention:
+  - 'Keep ARC runner controller and container-hooks up to date — circular JSON fixes land in patch releases'
+  - 'Monitor Kubernetes API server latency; high API server load increases the probability of this race condition'
+  - 'Pin to a specific ARC chart version in staging before rolling out to production runners'
+  - 'Check actions/runner#4302 for the specific v2.332.0 regression if pinned to that release'
+  - 'Set appropriate resource requests/limits so pod scheduling completes quickly and avoids API timeout races'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2056'
+    label: 'actions/checkout#2056: TypeError: Converting circular structure to JSON'
+  - url: 'https://github.com/actions/runner/issues/4302'
+    label: 'actions/runner#4302: ARC v2.332.0 container hook UID / permission regression'
+  - url: 'https://github.com/actions/actions-runner-controller'
+    label: 'Actions Runner Controller (ARC) — GitHub repository'

package/errors/runner-environment/cache-restore-windows-runner-silent-crash.yml

@@ -0,0 +1,130 @@
+id: runner-environment-196
+title: 'actions/cache restore silently crashes Windows runner — job jumps to Post cleanup with no error'
+category: runner-environment
+severity: silent-failure
+tags:
+  - cache
+  - windows
+  - crash
+  - silent-failure
+  - cargo
+  - large-cache
+  - post-cleanup
+patterns:
+  - regex: 'Cache hit for:.*\n(?:.*\n){0,3}Post job cleanup'
+    flags: 'i'
+  - regex: 'Cache hit for:[\s\S]{0,200}Post job cleanup'
+    flags: 'i'
+  - regex: 'Cache up-to-date\.\s*\(node:\d+\) \[DEP0040\] DeprecationWarning.*punycode'
+    flags: 'i'
+error_messages:
+  - 'Cache hit for: [key]'
+  - 'Post job cleanup.'
+  - 'Cache up-to-date.'
+root_cause: |
+  On Windows GitHub-hosted runners, actions/cache@v5 can silently crash the Node.js
+  runner process during cache restore when extracting very large cache archives (multi-GB
+  caches, e.g. Rust/Cargo registry + cache, large Maven/Gradle dependency trees).
+
+  The failure manifests as the job jumping directly from "Cache hit for: [key]" to
+  "Post job cleanup." with no intervening restore log lines and no error message.
+  The step exits with code 0 (success), but the cache was never extracted. Subsequent
+  build steps fail with missing dependency errors (e.g. "error: no such file or directory:
+  ~/.cargo/registry") rather than a cache-related error, making the root cause opaque.
+
+  The log sequence for affected runs:
+  1. "Cache hit for: [cache-key]"  (restore begins)
+  2. [no tar extraction log lines]
+  3. "Post job cleanup."            (job finishes or runner crashes)
+  4. "Cache up-to-date."
+  5. "(node:XXXX) [DEP0040] DeprecationWarning: The `punycode` module is deprecated"
+  6. "Post job cleanup."
+
+  Root cause analysis: The Windows runner process (Runner.Worker.exe) terminates
+  abnormally during tar/zstd decompression of the cache archive. This appears to be a
+  memory-related crash (similar to the Windows heap corruption pattern in upload-artifact,
+  tracked in toolkit#2406) triggered by the high memory pressure of decompressing large
+  archives within the Node.js 20 heap on Windows runners as of May 2026.
+
+  The crash is non-deterministic (intermittent) — the same cache key may restore
+  successfully on retry. Affected cache sizes are typically 1 GB+ uncompressed.
+  Rust Cargo caches (registry/index + registry/cache + git/db) are the most commonly
+  reported trigger.
+
+  Source: actions/cache#1754 (May 2026, Windows runner, Cargo cache).
+fix: |
+  Short-term workaround: Add `continue-on-error: true` to the cache restore step.
+  The job will proceed to the build step which will then reinstall dependencies from
+  scratch. The build takes longer but completes reliably.
+
+  Preferred workaround: Split the cache into smaller chunks. Rust/Cargo caches can be
+  split by caching registry/index, registry/cache, and git/db in separate cache steps
+  with different keys, keeping each archive under ~500 MB.
+
+  Alternative: Use sccache or a remote cache (e.g. Cloudflare R2 + sccache) instead of
+  actions/cache for Rust builds on Windows — this avoids large local archives entirely.
+
+  Long-term: Track actions/cache#1754 for an upstream fix. Adding
+  `ACTIONS_STEP_DEBUG: true` as a repository secret may reveal the crash signal in
+  verbose runner logs.
+fix_code:
+  - language: yaml
+    label: 'Short-term: continue-on-error to prevent job failure on crash'
+    code: |
+      - name: Restore Cargo cache
+        uses: actions/cache@v5
+        continue-on-error: true   # Job proceeds even if cache restore crashes
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+  - language: yaml
+    label: 'Split large Cargo cache into smaller chunks to avoid crash threshold'
+    code: |
+      - name: Restore Cargo registry index (small, fast)
+        uses: actions/cache@v5
+        with:
+          path: ~/.cargo/registry/index/
+          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-index-
+
+      - name: Restore Cargo registry cache (large packages)
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: ~/.cargo/registry/cache/
+          key: ${{ runner.os }}-cargo-cache-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-cache-
+
+      - name: Restore Cargo git sources
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-git-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Restore build target dir
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: target/
+          key: ${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.lock') }}
+
+prevention:
+  - 'Keep individual cache archives under ~500 MB by splitting large dependency trees (Cargo, Maven, Gradle) into multiple cache steps'
+  - 'Add continue-on-error: true to cache restore steps on Windows runners as a safety net for intermittent crashes'
+  - 'Monitor workflow durations — a sudden increase in Windows build time (cache miss equivalent) with no cache-related error in logs is a symptom of this crash'
+  - 'For Rust/Cargo on Windows runners, consider sccache with a remote backend to avoid large local cache archives entirely'
+  - 'Enable ACTIONS_STEP_DEBUG=true (as repository secret) to capture runner-level crash signals when this failure is suspected'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1754'
+    label: 'actions/cache#1754 — Windows runner randomly dies during cache restore (May 2026)'
+  - url: 'https://github.com/actions/cache#tips-for-using-cache'
+    label: 'actions/cache — usage tips and cache size guidance'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'Caching dependencies — limits and best practices'

package/errors/runner-environment/git-248-fetch-tags-shallow-clone-regression.yml

@@ -0,0 +1,100 @@
+id: runner-environment-190
+title: 'Git 2.48.0 silently stops fetching tags with fetch-tags: true on non-depth-1 shallow clones'
+category: runner-environment
+severity: silent-failure
+tags:
+  - git-version
+  - fetch-tags
+  - shallow-clone
+  - fetch-depth
+  - ubuntu-24.04
+  - regression
+  - checkout
+patterns:
+  - regex: 'git version 2\.48\.'
+    flags: 'i'
+  - regex: 'fetch-tags.*fetch-depth|fetch-depth.*fetch-tags'
+    flags: 'i'
+error_messages:
+  - "# No error — tags are silently absent after checkout with fetch-tags: true and fetch-depth: N on git 2.48.0"
+  - "fatal: No names found, cannot describe anything."
+  - "fatal: not a tag 'HEAD'"
+root_cause: |
+  Git 2.48.0 introduced a change in how `git fetch --depth=N` handles tag following for
+  direct refspec fetches. In git ≤ 2.47.x, when actions/checkout ran:
+
+    git fetch --depth=N origin +<sha>:refs/remotes/origin/<branch>
+
+  git would automatically follow tags reachable within the depth window — any tag pointing
+  to a commit within the fetched depth was included. This is known as automatic tag following.
+
+  Starting with git 2.48.0, automatic tag following is suppressed for direct refspec fetches
+  with `--depth`. Only the explicitly requested ref is fetched; no tags are included even if
+  they point to commits within the shallow clone window. The fetch log shows only the branch
+  ref fetched — no tag lines appear.
+
+  Result: `fetch-tags: true` combined with `fetch-depth: N` (where N > 1, such as 100, 383, 500)
+  silently returns no tags on runner images shipping git 2.48.0. The workflow log shows no error
+  and no warning — `git tag -l` returns empty. Downstream steps using git describe, semantic-release,
+  helm chart versioning, or any tool that reads git tags break with "no names found" or
+  "not a tag 'HEAD'" errors.
+
+  This regression first appeared when ubuntu-24.04 runner image updated from 20250105.1.0 to
+  20250113.1.0 (which shipped git 2.48.0). The issue was resolved in runner image 20250117.1.0+
+  when git was updated to 2.48.1 which patched the regression. Self-hosted runners running
+  git 2.48.0 remain affected.
+
+  Note: This is distinct from the existing known silent failure where fetch-depth: 1 silently
+  fetches no tags regardless of git version. That is expected shallow-clone behavior. This
+  regression affects fetch-depth: N > 1 scenarios that previously worked.
+fix: |
+  Use `fetch-depth: 0` when git tags are required. A full clone fetches all history and all
+  tags regardless of git version. This is the most reliable fix.
+
+  For large repositories where a full clone is too slow, add a separate fetch --tags step
+  immediately after checkout to explicitly fetch all tag objects:
+
+    git fetch --tags --force
+
+  Self-hosted runners on git 2.48.0 should upgrade to git 2.48.1 or later which patches
+  the tag following regression.
+fix_code:
+  - language: yaml
+    label: 'Use fetch-depth: 0 for reliable tag fetching (recommended)'
+    code: |
+      - name: Checkout with full history and all tags
+        uses: actions/checkout@v4
+        with:
+          # fetch-depth: 0 always fetches all commits and tags regardless of git version
+          fetch-depth: 0
+  - language: yaml
+    label: 'Add explicit git fetch --tags step after shallow checkout'
+    code: |
+      - name: Checkout (shallow)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 100
+          # fetch-tags: true is unreliable on git 2.48.0 — use explicit fetch instead
+
+      - name: Fetch tags explicitly (git-version-safe)
+        run: git fetch --tags --force
+  - language: yaml
+    label: 'Check git version in CI for debugging'
+    code: |
+      - name: Debug git version and tags
+        run: |
+          git --version
+          git tag -l | head -20
+          git describe --tags --always || echo "No reachable tags"
+prevention:
+  - 'Always use fetch-depth: 0 when git tags are required by downstream steps like git describe or semantic-release'
+  - 'Add a git tag -l debug step after checkout to verify tags are present before release tooling runs'
+  - 'For self-hosted runners, prefer git 2.48.1+ over 2.48.0 — the regression was patched in 2.48.1'
+  - 'Pin to fetch-depth: 0 in release workflows — the performance cost of a full clone is worth the reliability'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2041'
+    label: 'actions/checkout#2041: Tags no longer fetch with Git v2.48.0'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout — fetch-depth and fetch-tags input documentation'
+  - url: 'https://git-scm.com/docs/git-fetch#_description'
+    label: 'git fetch documentation — tag following with --depth'