@htekdev/actions-debugger 1.0.112 → 1.0.114

package/errors/permissions-auth/oidc-immutable-sub-claim-new-repo-trust-policy-mismatch.yml

@@ -0,0 +1,122 @@
+id: permissions-auth-067
+title: "OIDC immutable sub claim format for new repos breaks cloud trust policies"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - sub-claim
+  - aws
+  - azure
+  - gcp
+  - immutable
+  - trust-policy
+  - new-repo
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'AccessDenied.*AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'WorkloadIdentityPool.*rejected|token validation failed'
+    flags: 'i'
+  - regex: 'Credentials could not be loaded.*Could not load credentials from any providers'
+    flags: 'i'
+error_messages:
+  - "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers"
+  - "AuthorizationError: Token validation failed: subject claim does not match trust policy"
+  - "WorkloadIdentityPool: token was rejected: sub does not match condition"
+root_cause: |
+  Starting June 18, 2026, GitHub automatically applies a new **immutable subject
+  claim format** to all OIDC tokens issued for repositories created or renamed on
+  or after that date. The new format appends numeric IDs to the owner and repo
+  names:
+
+    Old format: repo:my-org/my-repo:ref:refs/heads/main
+    New format: repo:my-org-123456/my-repo-456789:ref:refs/heads/main
+
+  Cloud provider trust policies (AWS IAM `StringEquals`, GCP Workload Identity
+  Federation condition, Azure Federated Identity) that were copied from docs or
+  examples using only the human-readable `repo:OWNER/REPO:*` pattern will never
+  match the new immutable format. The claim is technically valid — GitHub issued it
+  correctly — but the trust policy simply rejects it, producing an
+  authorization error.
+
+  Existing repositories are NOT affected automatically; they must explicitly opt in
+  via the organization or repository OIDC settings. Only new repos created after
+  June 18, 2026 and repos renamed/transferred after that date receive the new
+  format unconditionally.
+
+  This is distinct from the repo-rename scenario (permissions-auth-019, which covers
+  mutable names changing) and the environment-block scenario (permissions-auth-054,
+  which covers the sub claim changing format when an `environment:` key is added).
+  This entry covers the baseline mismatch for freshly created repos.
+fix: |
+  Update your cloud provider trust policy to use the new immutable sub claim
+  format. Use the GitHub OIDC preview API to inspect the exact subject claim your
+  repository will produce before updating the policy:
+
+    GET /repos/{owner}/{repo}/actions/oidc/customization/sub
+
+  For AWS IAM, replace the StringEquals condition value with the new format
+  (including numeric IDs), or switch to StringLike with a wildcard:
+
+    repo:my-org-*/my-repo-*:ref:refs/heads/main
+
+  For GCP Workload Identity Federation, update the attribute condition string.
+  For Azure Federated Identity, update the subject field in the credential.
+
+  Alternatively, use GitHub's custom subject claim feature to define a simplified
+  subject that is stable across formats (e.g., only include `repository` and
+  `ref` fields that won't change).
+fix_code:
+  - language: yaml
+    label: "AWS — update IAM trust policy StringEquals to new immutable format"
+    code: |
+      # In your AWS IAM trust policy JSON (not YAML), update the condition:
+      # OLD — will fail for repos created after June 18, 2026:
+      #   "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main"
+      #
+      # NEW — use StringLike with wildcard to match both formats:
+      #   "token.actions.githubusercontent.com:sub": "repo:my-org*my-repo*:ref:refs/heads/main"
+      #
+      # Or use the exact immutable format shown in the OIDC preview API response.
+      #
+      # Alternatively, switch to a custom subject claim in GitHub OIDC settings
+      # that only includes fields you control.
+  - language: yaml
+    label: "GitHub Actions workflow is unchanged — the issue is in the cloud provider trust policy"
+    code: |
+      jobs:
+        deploy:
+          permissions:
+            id-token: write
+            contents: read
+          runs-on: ubuntu-latest
+          steps:
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/my-role
+                aws-region: us-east-1
+            # If the above step fails with "Not authorized to perform
+            # sts:AssumeRoleWithWebIdentity", the trust policy sub claim
+            # condition does not match the new immutable format.
+            # Update the IAM trust policy — not this workflow file.
+prevention:
+  - "Use StringLike with a wildcard pattern in cloud trust policies instead of
+    StringEquals with an exact sub claim value — this accommodates both old and
+    new immutable formats."
+  - "After creating a new repo, call the GitHub OIDC preview API
+    (GET /repos/{owner}/{repo}/actions/oidc/customization/sub) to see the
+    exact sub claim format before configuring the cloud trust policy."
+  - "Consider using GitHub's custom subject claim feature to pin a simplified,
+    stable sub claim structure that does not change with naming format updates."
+  - "Existing repos can opt in to the new format in repository or organization
+    OIDC settings — test in a staging environment first to confirm trust policies
+    are updated before enabling in production."
+docs:
+  - url: "https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/"
+    label: "GitHub Changelog: Immutable subject claims for GitHub Actions OIDC tokens (April 23, 2026)"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
+    label: "About security hardening with OpenID Connect"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/customizing-the-subject-claims-for-an-organization-or-repository"
+    label: "Customizing the subject claims for an organization or repository"

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

@@ -0,0 +1,122 @@
+id: permissions-auth-064
+title: 'GitHub OIDC Provider Intermittent 500 — Transient Token Request Failures'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - intermittent
+  - 500
+  - token-request
+  - transient
+  - retry
+patterns:
+  - regex: 'Request to OIDC provider failed with status 500'
+    flags: 'i'
+  - regex: 'Unable to get OIDC token.*500'
+    flags: 'i'
+  - regex: 'Failed to get ID token.*status.*500'
+    flags: 'i'
+error_messages:
+  - "Error: Unable to get OIDC token: Error: Request to OIDC provider failed with status 500"
+  - "Request to OIDC provider failed with status 500"
+  - "Error: Failed to get ID token: Request failed with status code 500"
+root_cause: |
+  GitHub's OIDC token endpoint (`https://token.actions.githubusercontent.com`) occasionally
+  returns HTTP **500 Internal Server Error** responses due to transient infrastructure issues
+  on GitHub's side. The failure is server-side and non-deterministic — workflows that ran
+  successfully hours ago may fail today, and re-running the identical job minutes later often
+  succeeds.
+
+  **This error is distinct from other OIDC failures:**
+
+  | Error | Cause | Fix |
+  |---|---|---|
+  | `Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable` | Missing `id-token: write` permission | Add permission to workflow |
+  | `OIDC: Could not parse JWT` | Malformed sub-claim or trust config | Fix cloud provider OIDC trust config |
+  | `429 Too Many Requests` | Rate limiting (large parallel matrix) | Add delays, reduce parallelism |
+  | **`status 500`** | **Transient GitHub infrastructure failure** | **Retry the job** |
+
+  The 500 occurs **after** the permission and environment variable checks pass. The OIDC
+  endpoint is reachable but GitHub's token minting service returned an internal error.
+
+  Common patterns where 500s surface:
+  - Workflows that run OIDC auth in every push/PR commit (high frequency)
+  - Parallel matrix jobs that all request tokens simultaneously
+  - Periods of GitHub infrastructure maintenance or elevated load
+fix: |
+  **Option 1 — Re-run the failed job.** The 500 is stateless; simply triggering a re-run
+  from the GitHub Actions UI is usually sufficient for non-blocking situations.
+
+  **Option 2 — Add a retry wrapper** around the cloud authentication step using an action
+  like `nick-fields/retry` or `Wandalen/wretry.action`. Wrap only the OIDC-dependent step
+  so that a transient 500 triggers an automatic retry without failing the entire workflow.
+
+  **Option 3 — Shell retry loop** for custom OIDC token fetches. Use a loop that retries
+  the request up to 3 times with a short backoff before failing.
+
+  There is no client-side configuration that prevents the server 500 — retrying is the
+  only mitigation.
+fix_code:
+  - language: yaml
+    label: 'Retry wrapper with nick-fields/retry'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+            # Wrap the OIDC-based auth step in a retry wrapper
+            - name: Configure AWS credentials (with retry)
+              uses: nick-fields/retry@v3
+              with:
+                max_attempts: 3
+                retry_wait_seconds: 15
+                timeout_minutes: 5
+                command: >
+                  aws sts get-caller-identity  # Or any OIDC-gated step
+
+            # Direct usage example — if your action supports retries natively
+            - name: Authenticate to AWS
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
+                aws-region: us-east-1
+
+  - language: yaml
+    label: 'Shell retry loop for custom OIDC token fetch'
+    code: |
+      steps:
+        - name: Fetch OIDC token with retry
+          run: |
+            MAX_ATTEMPTS=3
+            for i in $(seq 1 $MAX_ATTEMPTS); do
+              echo "Attempt $i of $MAX_ATTEMPTS..."
+              TOKEN=$(curl -sf \
+                -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+                "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=sts.amazonaws.com" \
+                | jq -r '.value') && {
+                echo "OIDC_TOKEN=${TOKEN}" >> $GITHUB_ENV
+                echo "Token acquired."
+                exit 0
+              }
+              echo "Attempt $i failed."
+              [ $i -lt $MAX_ATTEMPTS ] && sleep $((10 * i))
+            done
+            echo "All $MAX_ATTEMPTS attempts failed."
+            exit 1
+prevention:
+  - 'Add retry logic to all OIDC-based cloud auth steps — a transient 500 should not block a deployment that can safely retry'
+  - 'Distinguish error types in runbooks: 500 = transient (retry), 403 = permission error (fix config), 429 = rate limited (add delay)'
+  - 'Monitor https://www.githubstatus.com/ when 500s appear in multiple unrelated workflows simultaneously — it often indicates a GitHub Actions incident'
+  - 'For critical pipelines, implement automatic re-run-on-failure so OIDC 500s recover without manual intervention (e.g., peter-evans/create-or-update-comment + workflow_run trigger)'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect'
+    label: 'About security hardening with OpenID Connect — GitHub Actions docs'
+  - url: 'https://www.githubstatus.com/'
+    label: 'GitHub Status — check for active GitHub Actions incidents'
+  - url: 'https://github.com/nick-fields/retry'
+    label: 'nick-fields/retry — retry wrapper action for GitHub Actions'

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/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'