@htekdev/actions-debugger 1.0.116 → 1.0.118

package/errors/known-unsolved/node-action-post-step-wrong-inputs-nested-composite.yml

@@ -0,0 +1,133 @@
+id: known-unsolved-066
+title: 'Node Action Post Step Receives Wrong INPUT_* Env Vars When Called Through Nested Composite Action'
+category: known-unsolved
+severity: error
+tags:
+  - composite-actions
+  - post-step
+  - node-action
+  - nested
+  - inputs
+  - runner-bug
+  - savestate
+patterns:
+  - regex: 'Input required and not supplied:\s*\S+'
+    flags: 'i'
+  - regex: 'Post job cleanup\.\s*\n.*Input required'
+    flags: 'im'
+  - regex: 'post.*wrong.*input|INPUT_.*post.*ancestor'
+    flags: 'i'
+error_messages:
+  - 'Input required and not supplied: token'
+  - 'Input required and not supplied: test'
+  - 'Error: Input required and not supplied: <input-name>'
+  - 'Post job cleanup.'
+root_cause: |
+  Runner bug (actions/runner#3514, actions/runner#2030, open since 2022): when a Node.js
+  action that has a `post:` step is invoked through one or more composite action layers,
+  the runner restores the wrong `INPUT_*` environment variables for the post step execution.
+
+  At post-step execution time, the runner sets environment variables from the nearest
+  ancestor composite action's inputs, not from the inputs actually passed to the Node
+  action itself. For example:
+
+    Workflow → outer-composite (inputs: image-tag: "foo") → inner-composite
+      → node-action (inputs: image-tag: "foo")
+
+  The node action's main step correctly sees INPUT_IMAGE_TAG=foo.
+  In the post step, INPUT_IMAGE_TAG is absent or overwritten by the outer composite's
+  INPUT_IMAGE_TAG value (or another ancestor composite's value), causing:
+  - Required inputs to appear missing → visible error in post cleanup
+  - Optional inputs to resolve to wrong values → silent wrong behavior (e.g.,
+    devcontainers/ci pushes image with wrong tag; codeql-action uploads SARIF with
+    wrong token)
+
+  This affects ANY Node action with a post step that is called through composite
+  action nesting (depth ≥ 2). First-party actions affected include github/codeql-action
+  (fixed via workaround in codeql-action#2557) and pnpm/action-setup (issue #253).
+fix: |
+  GitHub has not fixed the runner bug. The canonical workaround is to persist inputs
+  in the action's main step using `core.saveState()` and read them back in the post
+  step using `core.getState()` instead of `core.getInput()`.
+
+  Actions consuming this workaround pattern:
+  - github/codeql-action (PR #2557): saveState for upload inputs
+  - Any action that reads inputs in its post step
+
+  If you maintain a Node action with a post step, add to your main.ts:
+    core.saveState('my-input', core.getInput('my-input'));
+  And in your post.ts:
+    const val = core.getState('my-input');  // use this instead of core.getInput
+
+  If you are a workflow author calling a third-party action through composite layers
+  and seeing wrong post-step behavior, check whether the action uses `core.getInput`
+  in its post step. If so, file an issue with the action maintainer referencing
+  actions/runner#3514 and the saveState workaround.
+fix_code:
+  - language: typescript
+    label: 'Action main.ts — persist inputs to state before post step runs'
+    code: |
+      import * as core from '@actions/core';
+
+      async function run() {
+        // Read inputs normally in main
+        const token = core.getInput('token', { required: true });
+        const imageName = core.getInput('image-name');
+
+        // Persist for post step (workaround for runner#3514)
+        core.saveState('token', token);
+        core.saveState('image-name', imageName);
+
+        // ... rest of main logic
+      }
+
+      run();
+  - language: typescript
+    label: 'Action post.ts — read from state, NOT core.getInput'
+    code: |
+      import * as core from '@actions/core';
+
+      async function runPost() {
+        // Use getState, NOT getInput — inputs are wrong in post step
+        // when called through nested composite action (runner#3514)
+        const token = core.getState('token');
+        const imageName = core.getState('image-name');
+
+        // ... post step logic using state values
+      }
+
+      runPost();
+  - language: yaml
+    label: 'action.yml — declare post step'
+    code: |
+      name: 'My Action'
+      inputs:
+        token:
+          required: true
+        image-name:
+          required: false
+      runs:
+        using: 'node20'
+        main: 'dist/main.js'
+        post: 'dist/post.js'
+        post-if: always()
+prevention:
+  - 'In any Node action with a post: step, always use core.saveState/core.getState for
+    inputs consumed in post, never core.getInput — this is defensive programming regardless
+    of nesting depth'
+  - 'Test your action in a composite action wrapper (at least 2 layers deep) to catch
+    this bug before publishing'
+  - 'Check release notes of actions/runner for fixes to this bug before assuming
+    the built-in behavior is fixed'
+  - 'When using actions with known post-step input bugs through composite layers,
+    consider calling them directly from the workflow (not nested in a composite) as
+    a temporary workaround'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3514'
+    label: 'actions/runner#3514 — Wrong environment passed to node post when called by composite called by composite'
+  - url: 'https://github.com/actions/runner/issues/2030'
+    label: 'actions/runner#2030 — Composite: Nested actions post steps have the wrong context (open since 2022)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#sending-values-to-the-pre-and-post-actions'
+    label: 'GitHub Docs — Sending values to pre and post actions (saveState/getState)'
+  - url: 'https://github.com/github/codeql-action/pull/2557'
+    label: 'codeql-action#2557 — Fix: persist inputs between upload action and post step (reference implementation)'

package/errors/known-unsolved/ubuntu-24-04-arm64-missing-binder-ashmem-kernel-modules.yml

@@ -0,0 +1,149 @@
+id: known-unsolved-065
+title: 'ubuntu-24.04-arm64 Hosted Runner Kernel Missing binder_linux and ashmem_linux Modules — Android Container Tests Fail'
+category: known-unsolved
+severity: limitation
+tags:
+  - ubuntu-24.04-arm64
+  - arm64
+  - kernel-modules
+  - android
+  - binder
+  - ashmem
+  - container
+  - known-limitation
+patterns:
+  - regex: 'modprobe: FATAL: Module binder_linux not found|modprobe.*binder_linux.*not found'
+    flags: 'i'
+  - regex: 'modprobe: FATAL: Module ashmem_linux not found|modprobe.*ashmem_linux.*not found'
+    flags: 'i'
+  - regex: '/dev/binder: No such file or directory|/dev/ashmem: No such file or directory'
+    flags: 'i'
+  - regex: 'CONFIG_ANDROID_BINDER_IPC.*not set|binder_linux.*absent.*kernel'
+    flags: 'i'
+error_messages:
+  - 'modprobe: FATAL: Module binder_linux not found in directory /lib/modules/<kernel>'
+  - 'modprobe: FATAL: Module ashmem_linux not found in directory /lib/modules/<kernel>'
+  - '/dev/binder: No such file or directory'
+  - '/dev/ashmem: No such file or directory'
+  - 'modprobe binder_linux exited with code 1'
+root_cause: |
+  The ubuntu-24.04-arm64 GitHub Actions hosted runner kernel is compiled WITHOUT
+  `CONFIG_ANDROID_BINDER_IPC=m` and `CONFIG_ANDROID_BINDERFS=m`. This means the
+  `binder_linux` and `ashmem_linux` kernel modules do not exist in
+  `/lib/modules/$(uname -r)/` on ARM64 runners.
+
+  Attempting `modprobe binder_linux` fails silently (exits 1) on ARM64 because
+  the module is simply absent from the kernel tree — it cannot be loaded even
+  as a privileged container.
+
+  **Why x86_64 hosted runners DO have these modules:**
+  The x86_64 ubuntu-24.04 hosted runners expose `binder` and `ashmem` because
+  they support the [GitHub Actions KVM Android hardware acceleration feature](https://github.blog/changelog/2024-04-02-github-actions-hardware-accelerated-android-virtualization-now-available/)
+  (released April 2024). The x86_64 kernel was explicitly built with Android
+  IPC support to enable this feature. The ARM64 kernel image is compiled
+  separately and was not built with these modules.
+
+  **Affected use cases:**
+  - Running [ReDroid](https://github.com/remote-android/redroid-doc) (GPU-enabled
+    Android-in-Docker) on native ARM64 CI for ARM-native app testing
+  - Running [Waydroid](https://waydro.id/) in ARM64 CI containers
+  - Any workflow that requires `/dev/binder` or `/dev/ashmem` devices
+
+  **Confirmed on:**
+  - ubuntu-24.04-arm64 image 20260531.15.1 (kernel aarch64, Azure westus2)
+  - Source: actions/runner-images#14184 (feature request, June 2026, open)
+
+  **No current workaround exists** — the module cannot be compiled from source
+  against the runner's kernel headers without the kernel source tree, and the
+  azure-linux kernel for ARM64 is not shipped with headers for out-of-tree
+  `binder_linux` builds. A request to add the modules to the ubuntu-24.04-arm64
+  image is tracked at runner-images#14184 and is currently open with no ETA.
+fix: |
+  **No complete fix is currently available for native ARM64 hosted runners.**
+
+  **Option 1 (Recommended): Use ubuntu-24.04 x86_64 runners for Android tests**
+
+  The x86_64 ubuntu-24.04 runner has `binder_linux` and `ashmem_linux` and
+  supports Android container tests via KVM acceleration. ARM-native testing can
+  be approximated via the Android native bridge, at the cost of some overhead:
+
+  ```yaml
+  android-test:
+    runs-on: ubuntu-24.04   # x86_64 — has binder_linux/ashmem_linux
+    steps:
+      - uses: actions/checkout@v6
+      - run: |
+          sudo modprobe binder_linux  # succeeds on x86_64
+          sudo modprobe ashmem_linux
+          # ... run ReDroid or Waydroid Android container tests
+  ```
+
+  **Option 2: Use real ARM hardware (Firebase Test Lab, self-hosted)**
+
+  For true ARM64 profiling (power/wakelock, native execution) use Firebase
+  Test Lab with physical Pixel hardware, or a self-hosted ARM64 runner on
+  hardware/VMs that expose binder devices.
+
+  **Option 3: Compile binder_linux from source (complex, unreliable)**
+
+  Without kernel headers matching the runner kernel, this is not practical
+  on GitHub-hosted runners.
+
+  **Track for a platform fix:** Follow actions/runner-images#14184 for progress
+  on adding `binder_linux`/`ashmem_linux` to the ubuntu-24.04-arm64 runner image.
+fix_code:
+  - language: yaml
+    label: 'Route Android container tests to x86_64 runner which has binder_linux/ashmem_linux'
+    code: |
+      jobs:
+        android-container-test:
+          # ubuntu-24.04-arm64 runner kernel is compiled without CONFIG_ANDROID_BINDER_IPC=m
+          # Use x86_64 runner which has binder_linux/ashmem_linux for KVM Android acceleration.
+          # Track runner-images#14184 for ARM64 kernel module support.
+          runs-on: ubuntu-24.04     # x86_64 — binder_linux available
+          container:
+            image: redroid/redroid:15.0.0-latest
+            options: --privileged
+          steps:
+            - uses: actions/checkout@v6
+            - name: Verify binder device
+              run: ls -la /dev/binder /dev/ashmem
+            - name: Run instrumented tests
+              run: ./gradlew connectedAndroidTest
+  - language: yaml
+    label: 'Guard ARM64 jobs against missing kernel modules'
+    code: |
+      jobs:
+        android-test:
+          runs-on: ${{ matrix.runner }}
+          strategy:
+            matrix:
+              runner: [ubuntu-24.04, ubuntu-24.04-arm64]
+          steps:
+            - uses: actions/checkout@v6
+            - name: Check binder_linux availability
+              id: binder-check
+              run: |
+                if modprobe binder_linux 2>/dev/null; then
+                  echo "available=true" >> "$GITHUB_OUTPUT"
+                else
+                  echo "available=false" >> "$GITHUB_OUTPUT"
+                  echo "::warning::binder_linux not available on $(uname -m) runner. Skipping Android container tests."
+                fi
+            - name: Run Android container tests
+              if: steps.binder-check.outputs.available == 'true'
+              run: ./run-android-tests.sh
+prevention:
+  - 'Do not assume binder_linux or ashmem_linux are available on ubuntu-24.04-arm64 hosted runners — the kernel was not built with CONFIG_ANDROID_BINDER_IPC=m.'
+  - 'Route Android container (ReDroid/Waydroid) CI tests to x86_64 ubuntu-24.04 runners until runner-images#14184 is resolved.'
+  - 'Always guard binder_linux/ashmem_linux modprobe calls with an availability check so ARM64 jobs fail gracefully rather than unexpectedly.'
+  - 'Track the ARM64 runner image feature request at actions/runner-images#14184 to know when the modules are added.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14184'
+    label: 'runner-images #14184 — Add binder_linux and ashmem_linux kernel modules to ubuntu-24.04-arm image (open Jun 2026)'
+  - url: 'https://github.com/remote-android/redroid-doc/issues/928'
+    label: 'redroid-doc #928 — GitHub Actions ubuntu-24.04-arm runners lack binder/ashmem kernel modules'
+  - url: 'https://github.blog/changelog/2024-04-02-github-actions-hardware-accelerated-android-virtualization-now-available/'
+    label: 'GitHub Changelog — Hardware-accelerated Android virtualization on x86_64 Actions runners'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24-arm64%2F20260531.15'
+    label: 'ubuntu-24.04-arm64 image 20260531.15.1 release notes'

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

@@ -0,0 +1,161 @@
+id: permissions-auth-069
+title: 'OIDC trust policy silently fails for repos missing required custom property claim — repository_property:* absent when property unset'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - custom-properties
+  - trust-policy
+  - aws
+  - azure
+  - gcp
+  - repository-property
+  - april-2026
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'AccessDenied.*AssumeRoleWithWebIdentity|WebIdentityErr.*AccessDenied'
+    flags: 'i'
+  - regex: 'Couldn''t retrieve OIDC token.*403|OIDC token.*invalid.*claim'
+    flags: 'i'
+  - regex: 'Error: Credentials could not be loaded.*OIDC'
+    flags: 'i'
+error_messages:
+  - 'Error: Not authorized to perform sts:AssumeRoleWithWebIdentity'
+  - 'AccessDenied: User: arn:aws:sts::... is not authorized to perform: sts:AssumeRoleWithWebIdentity'
+  - 'Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers'
+  - 'google.auth.exceptions.DefaultCredentialsError: OIDC token condition not satisfied'
+root_cause: |
+  GitHub Actions OIDC tokens now include `repository_property:{name}` claims for each
+  custom property set on the repository (generally available from April 2026). This
+  feature lets organizations create finer-grained cloud trust policies — for example,
+  only allowing OIDC authentication for repos whose `deploy_tier` custom property is
+  set to `production`.
+
+  However, the claim is **absent from the OIDC token when the property is not set on
+  the repository**. Cloud providers (AWS IAM, Azure AD, Google Cloud) evaluate a
+  missing claim as a condition failure:
+
+  - **AWS IAM** `Condition: { StringEquals: { "...repository_property:deploy_tier": "production" } }`
+    → `AccessDenied` if the repo has no `deploy_tier` property set
+  - **GCP** workload identity attribute conditions on `attribute.repository_property_*`
+    → condition evaluates false, token exchange rejected
+
+  Common scenarios that trigger this:
+  1. **Org-wide trust policy** uses a custom property claim, but individual repos have
+     not been tagged with the required property.
+  2. **Property renamed or deleted** — the trust policy still references the old
+     property name; the token no longer includes the old claim.
+  3. **Fork PRs** — forked repositories do not inherit the parent org's custom
+     properties; OIDC tokens from fork CI lack the expected claims.
+  4. **New repo** — a repository was added to the org after the trust policy was
+     configured; the property has not yet been applied to it.
+
+  The error message (`Not authorized to perform sts:AssumeRoleWithWebIdentity`) is
+  identical to other OIDC failures (wrong `sub`, wrong `aud`, expired token) and gives
+  no indication that a missing custom property claim is the cause.
+fix: |
+  1. **Verify the claim is present in the token**: Use the GitHub OIDC debugger or
+     print the decoded token payload in a workflow step to confirm the
+     `repository_property:{name}` claim exists and has the expected value.
+
+  2. **Ensure the custom property is set on all target repos**: In the org settings,
+     verify that every repository expected to use the trust policy has the required
+     property configured. Newly added repos will not have it by default.
+
+  3. **Make the condition optional (if the property may not always be set)**:
+     In AWS IAM, use `StringLike` with a wildcard or remove the custom-property
+     condition from the trust policy; use a separate, more permissive role for repos
+     without the property.
+
+  4. **For fork PRs**: custom properties on the upstream org do not flow to forks.
+     Avoid trust policies that require custom property claims in workflows triggered
+     by `pull_request` from external forks.
+fix_code:
+  - language: yaml
+    label: 'Debug step — print OIDC token claims to diagnose missing custom property'
+    code: |
+      jobs:
+        debug-oidc:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+          steps:
+            - name: Fetch OIDC token and decode payload
+              run: |
+                TOKEN=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+                  "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.amazonaws.com" | jq -r '.value')
+                # Decode payload (second segment of JWT, base64url-encoded)
+                echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' \
+                  | base64 -d 2>/dev/null | jq .
+              # Look for "repository_property:your_property_name" in the output.
+              # If the claim is missing, the repo does not have that property set.
+
+  - language: yaml
+    label: 'AWS IAM trust policy — correct use of repository_property claim'
+    code: |
+      # AWS IAM role trust policy (JSON, not YAML — shown here for reference)
+      # Only allow OIDC from repos where custom property "deploy_tier" = "production"
+      {
+        "Version": "2012-10-17",
+        "Statement": [{
+          "Effect": "Allow",
+          "Principal": { "Federated": "arn:aws:iam::ACCOUNT:oidc-provider/token.actions.githubusercontent.com" },
+          "Action": "sts:AssumeRoleWithWebIdentity",
+          "Condition": {
+            "StringEquals": {
+              "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
+              "token.actions.githubusercontent.com:repository_property:deploy_tier": "production"
+            }
+          }
+        }]
+      }
+      # IMPORTANT: Every repo that runs this workflow MUST have the "deploy_tier"
+      # custom property set to "production" in org settings. If the property is
+      # unset or absent, the token will not include the claim and the assume-role
+      # call will return AccessDenied.
+
+  - language: yaml
+    label: 'Workflow — ensure the custom property claim is available before assuming role'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+            # Verify the custom property claim is present before assuming the role
+            - name: Validate OIDC custom property claim
+              run: |
+                TOKEN=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+                  "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.amazonaws.com" | jq -r '.value')
+                PAYLOAD=$(echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null)
+                TIER=$(echo "$PAYLOAD" | jq -r '."repository_property:deploy_tier" // "MISSING"')
+                echo "deploy_tier claim: $TIER"
+                if [[ "$TIER" != "production" ]]; then
+                  echo "::error::Repository custom property 'deploy_tier' is not set to 'production'. Set it in org settings before running this workflow."
+                  exit 1
+                fi
+
+            - name: Configure AWS credentials via OIDC
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/my-production-deploy-role
+                aws-region: us-east-1
+
+prevention:
+  - 'Maintain a registry of which repositories have each custom property set — before applying a trust policy that requires a custom property claim, verify all target repos have the property configured.'
+  - 'When adding a new repo to an org that uses OIDC custom property trust policies, immediately apply the required custom properties before running any workflows that assume cloud roles.'
+  - 'Do not use repository custom property claims in OIDC trust policies for workflows triggered by external fork pull requests — forks do not inherit the upstream org''s custom properties.'
+  - 'Add a preflight validation step to workflows that assume cloud roles — verify the expected repository_property:* claim is present in the OIDC token before calling the cloud provider.'
+  - 'If a custom property is renamed or removed, update all OIDC trust policies before the change takes effect to avoid sudden AccessDenied failures.'
+docs:
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/#actions-oidc-tokens-now-support-repository-custom-properties'
+    label: 'GitHub Changelog: OIDC tokens now support repository custom properties (April 2026)'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims'
+    label: 'GitHub Docs: Customizing OIDC token claims — repository custom properties'
+  - url: 'https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization'
+    label: 'GitHub Docs: Managing custom properties for repositories in your organization'

package/errors/runner-environment/arc-autoscalinglistener-ephemeralrunnerset-stale-after-upgrade.yml

@@ -0,0 +1,134 @@
+id: runner-environment-211
+title: 'ARC Controller Upgrade Leaves Stale AutoscalingListener and EphemeralRunnerSet — Manual Intervention Required'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - actions-runner-controller
+  - kubernetes
+  - upgrade
+  - autoscaling
+  - helm
+  - stale-controller
+patterns:
+  - regex: 'AutoscalingListener.*spec\.image.*old.*version|spec\.image.*ghcr\.io/actions.*stale'
+    flags: 'i'
+  - regex: 'app\.kubernetes\.io/version.*mismatch|helm\.sh/chart.*stale.*controller'
+    flags: 'i'
+  - regex: 'RunnerScaleSet.*stale.*image|EphemeralRunnerSet.*old.*version'
+    flags: 'i'
+error_messages:
+  - 'AutoscalingListener CRs retain stale controller image after controller upgrade'
+  - 'EphemeralRunnerSet retains stale version labels after controller upgrade'
+  - 'spec.image still points to old controller version after helm upgrade'
+root_cause: |
+  When upgrading the `gha-runner-scale-set-controller` Helm chart, two
+  controller-managed objects are NOT updated to reflect the new version:
+
+  1. **AutoscalingListener CRs** — retain the old controller image in `spec.image`
+  2. **EphemeralRunnerSet objects** — retain old version labels
+     (`app.kubernetes.io/version`, `helm.sh/chart`)
+
+  The root cause is that the controller gates reconciliation on a **spec hash**.
+  A controller-only upgrade does not change any `AutoscalingRunnerSet` spec, so
+  the hash is identical and the controller skips reconciliation of both objects
+  entirely. The `updateStrategy` flag only governs spec-change rollout, not
+  controller version upgrades.
+
+  **Object hierarchy affected:**
+  ```
+  AutoscalingRunnerSet   (Helm-managed)
+  ├── AutoscalingListener   ← stale image after controller upgrade
+  └── EphemeralRunnerSet    ← stale labels/spec after controller upgrade
+          └── EphemeralRunner
+  ```
+
+  For minor version bumps (e.g. 0.14.1 → 0.14.2) the staleness may appear
+  cosmetic. For **major upgrades** where the `EphemeralRunnerSet` or
+  `EphemeralRunner` spec has breaking changes (new required fields, removed
+  fields, changed defaults), stale objects under a new controller can cause
+  runtime failures — jobs queued but never dispatched, runner pods using the old
+  image's entrypoint, or scale-set reporting incorrect capacity.
+
+  **Version confirmed affected:** controller 0.14.2 / scale-set 0.14.2,
+  Kubernetes RKE2 (reproducible on any Kubernetes distribution).
+fix: |
+  Two separate manual steps are required after every controller upgrade where
+  AutoscalingListener or EphemeralRunnerSet spec has changed:
+
+  **Step 1 — Delete all AutoscalingListener CRs** (the controller recreates them
+  immediately with the new image; runner pods are unaffected):
+
+  ```bash
+  kubectl delete autoscalinglisteners -A --all
+  ```
+
+  Verify the new version is used after recreation:
+  ```bash
+  kubectl get autoscalinglisteners -A \
+    -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.image}{"\n"}{end}'
+  ```
+
+  **Step 2 — Trigger EphemeralRunnerSet reconciliation** via a dummy annotation
+  change to `spec.template.spec` (a change to `minRunners` alone is NOT
+  sufficient — it only affects the AutoscalingListener hash, not the
+  EphemeralRunnerSet hash):
+
+  ```yaml
+  spec:
+    template:
+      metadata:
+        annotations:
+          upgrade-trigger: "0.14.2"   # bump on each controller upgrade
+  ```
+
+  This triggers a graceful transition: the old EphemeralRunnerSet drains
+  (in-progress jobs complete) while the new one starts accepting jobs
+  immediately. Remove the annotation in a follow-up commit.
+
+  **Verify EphemeralRunnerSet version labels are updated:**
+  ```bash
+  kubectl get ephemeralrunnersets -A \
+    -o custom-columns='NAME:.metadata.name,VERSION:.metadata.labels.app\.kubernetes\.io/version'
+  ```
+fix_code:
+  - language: yaml
+    label: 'Trigger EphemeralRunnerSet reconciliation via dummy annotation (per scale set)'
+    code: |
+      # In your AutoscalingRunnerSet HelmRelease or values.yaml:
+      # Add a dummy annotation to spec.template.spec to force EphemeralRunnerSet
+      # reconciliation after a controller upgrade.
+      # Remove the annotation in a follow-up commit once migration is confirmed.
+      spec:
+        template:
+          metadata:
+            annotations:
+              upgrade-trigger: "0.14.2"   # bump to new controller version
+  - language: yaml
+    label: 'Post-upgrade runbook as a one-off Job'
+    code: |
+      # After upgrading the controller chart, run this in CI or manually:
+      # Step 1: delete stale AutoscalingListener CRs (controller recreates immediately)
+      # kubectl delete autoscalinglisteners -A --all
+      #
+      # Step 2: patch each AutoscalingRunnerSet with a dummy annotation to force
+      # EphemeralRunnerSet reconciliation:
+      # kubectl annotate autoscalingrunnersets -A --all \
+      #   upgrade-trigger=$(date +%s) --overwrite
+      #
+      # Note: kubectl annotate updates metadata.annotations, not spec.template.spec,
+      # so it does NOT trigger EphemeralRunnerSet reconciliation. Use the values
+      # approach above (spec.template.metadata.annotations) instead.
+prevention:
+  - 'After every ARC controller upgrade, check AutoscalingListener images and EphemeralRunnerSet labels before routing production traffic.'
+  - 'Add a post-upgrade step to your CI/CD pipeline that deletes AutoscalingListener CRs and adds a dummy upgrade-trigger annotation.'
+  - 'Pin a dummy annotation like `upgrade-trigger: "<version>"` in your HelmRelease values and bump it with each controller upgrade.'
+  - 'Subscribe to actions/actions-runner-controller releases and review EphemeralRunnerSet spec changes before upgrading.'
+  - 'Track the upstream issue at actions/actions-runner-controller#4513 for a platform-side fix.'
+docs:
+  - url: 'https://github.com/actions/actions-runner-controller/issues/4513'
+    label: 'ARC #4513 — AutoscalingListener and EphemeralRunnerSet retain stale controller image/labels after upgrade (open Jun 2026)'
+  - url: 'https://github.com/actions/actions-runner-controller/blob/master/TROUBLESHOOTING.md'
+    label: 'ARC Troubleshooting Guide'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller'
+    label: 'About Actions Runner Controller'