@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/runner-environment/checkout-windows-ebusy-lock.yml

@@ -0,0 +1,124 @@
+id: runner-environment-042
+title: "actions/checkout EBUSY File Lock on Windows Self-Hosted Runners"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - self-hosted
+  - checkout
+  - ebusy
+  - file-lock
+  - git-fsmonitor
+patterns:
+  - regex: "EBUSY.*resource busy or locked"
+    flags: "i"
+  - regex: "File was unable to be removed.*EBUSY"
+    flags: "i"
+  - regex: "Unable to remove.*_temp.*EBUSY"
+    flags: "i"
+error_messages:
+  - "Error: File was unable to be removed Error: EBUSY: resource busy or locked, rmdir 'C:\\Users\\...\\runner\\_temp\\...'"
+  - "Error: EBUSY: resource busy or locked, rmdir"
+  - "Error: The process cannot access the file because it is being used by another process"
+root_cause: |
+  On Windows self-hosted runners, `actions/checkout` fails with an `EBUSY` (resource
+  busy or locked) error when attempting to clean up temp directories during checkout.
+
+  **Primary cause — Git FSMonitor:**
+  Git's `core.fsmonitor` daemon (enabled by default in Git 2.36+) keeps a file handle
+  open on the repository directory. When `actions/checkout` tries to remove or clean the
+  `_temp` directory between runs, the FSMonitor process holds the lock, causing EBUSY.
+
+  **Secondary causes:**
+  - Windows Defender / antivirus scanning files that checkout is trying to delete
+  - Other processes (IDE file watchers, npm watchers, running Node processes) holding
+    handles on workspace files
+  - Concurrent runner jobs accessing the same workspace directory
+
+  **Why Windows only:**
+  Linux/macOS do not enforce EBUSY locks in the same way. Windows file locking is
+  advisory on Unix but mandatory on NTFS, so the same handle that would succeed on
+  Linux causes a hard error on Windows.
+
+  Source: actions/checkout#1388
+fix: |
+  **Option 1 (recommended): Disable Git FSMonitor on the runner**
+
+  Configure Git globally on the self-hosted runner to disable fsmonitor:
+  ```
+  git config --global core.fsmonitor false
+  git config --global core.useBuiltinFSMonitor false
+  ```
+
+  **Option 2: Add a pre-checkout cleanup step**
+
+  Kill any lingering Git processes before checkout:
+  ```yaml
+  - name: Kill lingering git processes
+    shell: pwsh
+    run: Get-Process -Name "git" -ErrorAction SilentlyContinue | Stop-Process -Force
+  ```
+
+  **Option 3: Configure antivirus exclusions**
+
+  Add the runner workspace directory (e.g., `C:\actions-runner\_work\`) to Windows
+  Defender's exclusion list on the self-hosted runner machine.
+
+  **Option 4: Use `clean: false` and handle cleanup manually**
+
+  Setting `clean: false` on `actions/checkout` prevents the step from attempting to
+  clean the workspace, avoiding the lock conflict entirely.
+fix_code:
+  - language: yaml
+    label: "Workaround — disable git FSMonitor before checkout"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            # Kill git fsmonitor daemon before checkout to release file locks
+            - name: Disable git fsmonitor
+              shell: pwsh
+              run: |
+                git config --global core.fsmonitor false
+                git config --global core.useBuiltinFSMonitor false
+                Get-Process -Name "git" -ErrorAction SilentlyContinue | Stop-Process -Force
+
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Workaround — skip workspace clean to avoid EBUSY on _temp"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                clean: false   # Skip workspace clean; avoids EBUSY on locked dirs
+  - language: yaml
+    label: "Workaround — retry checkout on EBUSY failure"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - name: Checkout with retry
+              uses: nick-fields/retry@v3
+              with:
+                timeout_minutes: 5
+                max_attempts: 3
+                command: git checkout
+            - uses: actions/checkout@v4
+prevention:
+  - "Disable Git FSMonitor globally on Windows self-hosted runners: `git config --global core.fsmonitor false`."
+  - "Add the runner `_work` directory to Windows Defender exclusions — AV scanning causes EBUSY on files checkout needs to delete."
+  - "Avoid running multiple workflow jobs concurrently on the same workspace directory on a single Windows self-hosted runner."
+  - "Upgrade to `actions/checkout@v4` — later versions have improved retry logic and are more resilient to transient locks."
+  - "Consider using ephemeral self-hosted runners that start fresh for each job, eliminating stale workspace lock issues entirely."
+docs:
+  - url: "https://github.com/actions/checkout/issues/1388"
+    label: "actions/checkout#1388 — EBUSY resource busy or locked on Windows self-hosted"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "GitHub Docs: About self-hosted runners"
+  - url: "https://git-scm.com/docs/git-config#Documentation/git-config.txt-corefsmonitor"
+    label: "Git config: core.fsmonitor"

package/errors/runner-environment/deprecated-action-version-auto-rejected.yml

@@ -0,0 +1,89 @@
+id: runner-environment-037
+title: "Deprecated Action Version Automatically Rejected by Runner"
+category: runner-environment
+severity: error
+tags:
+  - deprecated
+  - action-version
+  - actions-cache
+  - breaking-change
+  - pinning
+  - migration
+patterns:
+  - regex: "This request has been automatically failed because it uses a deprecated version of"
+    flags: "i"
+  - regex: "uses a deprecated version of `actions/(cache|checkout|upload-artifact|download-artifact)"
+    flags: "i"
+  - regex: "Please update your workflow to use v[0-9]+ of `actions/"
+    flags: "i"
+error_messages:
+  - "Error: This request has been automatically failed because it uses a deprecated version of `actions/cache: v4.0.2`. Please update your workflow to use v3/v4 of actions/cache. Learn more: https://github.blog/changelog/..."
+  - "Error: This request has been automatically failed because it uses a deprecated version of `actions/upload-artifact: v1`."
+root_cause: |
+  GitHub periodically deprecates specific minor/patch version tags of official actions (e.g.,
+  actions/cache, actions/checkout, actions/upload-artifact). When a workflow pins a deprecated
+  specific version (e.g., @v4.0.2 instead of @v4), the Actions runner rejects the entire run
+  immediately with an "automatically failed" message — before executing any step logic.
+
+  This is distinct from a runtime failure: the runner halts before any user code runs, which
+  means logs contain only the rejection message and no build output.
+
+  Deprecation schedules and affected versions are announced via GitHub Changelog. Common
+  scenarios that trigger this:
+  - Pinning exact minor/patch SHA-like versions (v4.0.2) instead of major aliases (v4)
+  - Old workflow files that predate a deprecation cycle and have not been updated
+  - Third-party or internal actions that internally depend on deprecated toolkit versions
+  - Dependabot bumping a minor version that happens to be on the deprecated list
+
+  Affected actions as of 2024-2026 include actions/cache v1/v2, specific v4.0.x minor pins,
+  actions/upload-artifact v1/v2, and associated @actions/toolkit package versions used as
+  dependencies in published actions.
+fix: |
+  Update all action `uses:` references to a currently supported version tag.
+
+  For official GitHub actions, always prefer the major version alias (e.g., @v4, @v3) rather
+  than pinning a minor or patch version. This ensures your workflow automatically receives
+  non-breaking updates and avoids deprecation gates.
+
+  To track deprecation notices proactively:
+  - Watch or subscribe to https://github.blog/changelog/ for "breaking changes" announcements
+  - Enable Dependabot for GitHub Actions in your repository
+  - Check the action's GitHub releases page for deprecation notices in release notes
+fix_code:
+  - language: yaml
+    label: "Use major version alias instead of pinned minor version"
+    code: |
+      jobs:
+        build:
+          steps:
+            # ❌ Pinned minor version — may be auto-rejected after deprecation
+            - uses: actions/cache@v4.0.2
+
+            # ✅ Major alias — always points to latest supported minor in that major
+            - uses: actions/cache@v4
+
+            # ✅ Full SHA pin — immune to deprecation gates (security-conscious alternative)
+            - uses: actions/cache@5a3ec84eff668545956fd18022155c47c3f8e48
+  - language: yaml
+    label: "Enable Dependabot to keep action versions current"
+    code: |
+      # .github/dependabot.yml
+      version: 2
+      updates:
+        - package-ecosystem: "github-actions"
+          directory: "/"
+          schedule:
+            interval: "weekly"
+prevention:
+  - "Use major version aliases (@v4, @v3) instead of exact minor/patch versions for official GitHub actions."
+  - "Subscribe to github.blog/changelog and watch for 'Notice of upcoming releases and breaking changes for GitHub Actions' posts."
+  - "Enable Dependabot for the github-actions ecosystem in your repository to auto-bump pinned versions."
+  - "Periodically audit your workflows for pinned minor/patch versions: grep -r 'uses:' .github/workflows/ | grep -E '@v[0-9]+\\.[0-9]+'"
+  - "When using SHA pinning for security, use a tool like StepSecurity's Harden-Runner or pin-github-action to maintain fresh SHAs."
+docs:
+  - url: "https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions/#actions-cache-v1-v2-and-actions-toolkit-cache-package-closing-down"
+    label: "GitHub Changelog — actions/cache v1/v2 deprecation notice"
+  - url: "https://github.com/orgs/community/discussions/151729"
+    label: "Community discussion #151729 — deprecated action version auto-failure"
+  - url: "https://github.com/actions/setup-python/issues/1037"
+    label: "actions/setup-python #1037 — reports of deprecated cache version failures"

package/errors/runner-environment/github-hosted-runner-disk-space-full.yml

@@ -0,0 +1,85 @@
+id: runner-environment-048
+title: "GitHub-hosted runner disk space exhausted (No space left on device)"
+category: runner-environment
+severity: error
+tags:
+  - disk-space
+  - ubuntu
+  - docker
+  - storage
+  - enospc
+patterns:
+  - regex: "No space left on device"
+    flags: "i"
+  - regex: "ENOSPC: no space left on device"
+    flags: "i"
+  - regex: "Disk usage: 100%"
+    flags: "i"
+  - regex: "write .*: no space left on device"
+    flags: "i"
+error_messages:
+  - "No space left on device"
+  - "Error: ENOSPC: no space left on device, write"
+  - "OSError: [Errno 28] No space left on device"
+root_cause: |
+  GitHub-hosted ubuntu-latest runners start with approximately 14-25 GB of free
+  disk space after the OS and pre-installed toolchains occupy the rest of the
+  ~80 GB disk. Workflows that build large Docker images, run multi-stage builds,
+  download large artifacts, or install additional software can exhaust this
+  budget mid-job.
+
+  Common culprits:
+  - Docker build layers accumulating in /var/lib/docker (no automatic pruning)
+  - Android SDK, .NET SDKs, Haskell GHC, and other large pre-installed tools
+    consuming 50+ GB of disk that most workflows never need
+  - Multiple matrix jobs each pulling large container images on the same runner
+    (each job gets a fresh runner, but a single job's steps share one disk)
+fix: |
+  Add a disk-space cleanup step at the start of your job before any build steps.
+  The jlumbroso/free-disk-space action removes pre-installed tools you don't
+  need, recovering 30-60 GB.
+
+  Alternatively, use docker system prune to clean up intermediate layers after
+  each build stage, or split large jobs across multiple workflows.
+fix_code:
+  - language: yaml
+    label: "Use free-disk-space action at job start"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Free disk space
+              uses: jlumbroso/free-disk-space@v1.3.1
+              with:
+                tool-cache: false
+                android: true
+                dotnet: true
+                haskell: true
+                large-packages: true
+                swap-storage: true
+            - uses: actions/checkout@v4
+            - name: Build Docker image
+              run: docker build -t myapp .
+  - language: yaml
+    label: "Prune Docker intermediate layers between build stages"
+    code: |
+      - name: Build builder stage
+        run: docker build --target builder -t myapp:builder .
+      - name: Prune intermediate layers
+        run: docker image prune -f
+      - name: Build final image
+        run: docker build -t myapp:final .
+prevention:
+  - "Add jlumbroso/free-disk-space as the first step in any disk-intensive job"
+  - "Use multi-stage Docker builds and prune builder images after the final stage"
+  - "Run df -h early in the job to baseline free space and catch issues before they crash"
+  - "Consider GitHub larger runners (30-100 GB disk) for builds that legitimately need space"
+  - "Cache Docker layers with type=gha to avoid re-downloading the same base images"
+docs:
+  - url: "https://github.com/jlumbroso/free-disk-space"
+    label: "jlumbroso/free-disk-space — reclaim disk on GitHub-hosted runners"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs — Hosted runner hardware resources and disk space"
+  - url: "https://github.com/actions/runner-images/issues/2840"
+    label: "runner-images#2840 — Disk space workarounds discussion"

package/errors/runner-environment/github-path-same-step-not-found.yml

@@ -0,0 +1,114 @@
+id: runner-environment-040
+title: "GITHUB_PATH Updates Are Not Available in the Same Step That Writes Them"
+category: runner-environment
+severity: silent-failure
+tags:
+  - GITHUB_PATH
+  - GITHUB_ENV
+  - path
+  - environment-file
+  - command-not-found
+  - same-step
+patterns:
+  - regex: "command not found"
+    flags: "i"
+  - regex: "not recognized as.*cmdlet|not recognized as.*function"
+    flags: "i"
+  - regex: "GITHUB_PATH.*same step|same step.*GITHUB_PATH"
+    flags: "i"
+error_messages:
+  - "/bin/bash: line X: my-tool: command not found"
+  - "The term 'my-tool' is not recognized as the name of a cmdlet, function, script file, or executable program"
+root_cause: |
+  When you write a directory path to `$GITHUB_PATH` (or an environment variable to
+  `$GITHUB_ENV`), the change is **NOT available in the same `run:` step** that writes
+  the file. It only takes effect for **subsequent steps** in the same job.
+
+  The runner reads the environment files between steps — not mid-step. The typical
+  developer mistake is:
+
+  ```yaml
+  - name: Install and use tool
+    run: |
+      echo "$HOME/.local/bin" >> $GITHUB_PATH   # writes to GITHUB_PATH
+      my-tool --version                           # ❌ fails — PATH not updated yet
+  ```
+
+  The same applies to `$GITHUB_ENV` — variables written to the env file are not
+  accessible via `${{ env.VAR }}` or as shell variables in the same step.
+
+  Additionally, using `>` instead of `>>` to write to `$GITHUB_PATH` or `$GITHUB_ENV`
+  overwrites the entire file, wiping all previously set paths/variables and causing
+  unexpected "command not found" errors in later steps.
+
+  Sources: GitHub Community #80916, nektos/act issue #2637, GitHub Docs
+fix: |
+  Split the install/configure step from the step that uses the tool. Write to
+  `$GITHUB_PATH` or `$GITHUB_ENV` in one step, then use the tool/variable in a
+  subsequent step.
+
+  For the current step only, modify `$PATH` directly in the shell environment
+  (not via `$GITHUB_PATH`) if you need immediate access.
+
+  Always use `>>` (append) when writing to `$GITHUB_PATH` or `$GITHUB_ENV` — never
+  `>` (overwrite).
+fix_code:
+  - language: yaml
+    label: "Broken — tool used in same step as GITHUB_PATH write"
+    code: |
+      # ❌ BROKEN: my-tool not found because PATH not updated until next step
+      - name: Install and use tool
+        run: |
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          my-tool --version   # fails: command not found
+  - language: yaml
+    label: "Fixed — split into two steps"
+    code: |
+      # ✅ FIXED: separate steps so runner reads GITHUB_PATH between them
+      - name: Add tool to PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Use tool (PATH now includes ~/.local/bin)
+        run: my-tool --version
+  - language: yaml
+    label: "Fixed — same-step access via direct PATH export (no GITHUB_PATH)"
+    code: |
+      # ✅ ALTERNATIVE: Export PATH directly in the same step if splitting isn't possible
+      - name: Install and use tool in same step
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"   # takes effect immediately in this step
+          my-tool --version
+          # Also persist for later steps:
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+  - language: yaml
+    label: "Fixed — GITHUB_ENV: split the set and the use"
+    code: |
+      # ❌ BROKEN: Variable not available yet in same step
+      - run: |
+          echo "MY_VAR=hello" >> $GITHUB_ENV
+          echo "$MY_VAR"   # empty — not yet loaded
+
+      # ✅ FIXED: Use in a later step
+      - run: echo "MY_VAR=hello" >> $GITHUB_ENV
+      - run: echo "$MY_VAR"    # prints 'hello'
+  - language: yaml
+    label: "Warning — always append (>>) never overwrite (>)"
+    code: |
+      # ❌ BROKEN: Overwrites GITHUB_PATH, removing all previously set paths
+      echo "/new/path" > $GITHUB_PATH
+
+      # ✅ FIXED: Append to preserve existing entries
+      echo "/new/path" >> $GITHUB_PATH
+prevention:
+  - "Never use the result of `$GITHUB_PATH` or `$GITHUB_ENV` writes in the same `run:` step — they take effect in the next step."
+  - "Always use `>>` (append) not `>` (overwrite) when writing to `$GITHUB_PATH` or `$GITHUB_ENV`."
+  - "If you need a tool available in the same step, export `PATH` directly in the shell command: `export PATH=\"/dir:$PATH\"` before calling the tool."
+  - "On Windows (PowerShell), use `Add-Content` or `Out-File -Append` — do not use `Set-Content` which overwrites the file."
+  - "Check the GitHub Actions docs section on 'environment files' to understand the step boundary at which env files are read."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path"
+    label: "GitHub Docs: Workflow commands — Adding a system path (GITHUB_PATH)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable"
+    label: "GitHub Docs: Workflow commands — Setting an environment variable (GITHUB_ENV)"
+  - url: "https://github.com/orgs/community/discussions/80916"
+    label: "GitHub Community #80916 — GITHUB_PATH not available same step"

package/errors/runner-environment/github-script-v6-octokit-rest-actions-not-function.yml

@@ -0,0 +1,87 @@
+id: runner-environment-047
+title: "actions/github-script@v6 octokit.rest.actions.* Methods Not Available (Stale Octokit Bundle)"
+category: runner-environment
+severity: error
+tags:
+  - github-script
+  - octokit
+  - rest-api
+  - variables-api
+  - actions-api
+  - version-mismatch
+patterns:
+  - regex: "github\\.rest\\.actions\\.[a-zA-Z]+ is not a function"
+    flags: "i"
+  - regex: "TypeError.*github\\.rest\\.actions\\."
+    flags: "i"
+  - regex: "Unhandled error: TypeError.*github\\.rest\\."
+    flags: "i"
+error_messages:
+  - "TypeError: github.rest.actions.createRepoVariable is not a function"
+  - "TypeError: github.rest.actions.listRepoVariables is not a function"
+  - "TypeError: github.rest.actions.getEnvironmentVariable is not a function"
+  - "TypeError: github.rest.actions.updateRepoVariable is not a function"
+  - "Unhandled error: TypeError: github.rest.actions.createOrUpdateRepoVariable is not a function"
+root_cause: |
+  `actions/github-script@v6` bundles `@octokit/plugin-rest-endpoint-methods` v6.3.0, which
+  predates GitHub's Variables API endpoints and several other newer REST endpoints added to the
+  GitHub API in 2023. These methods were added to the Octokit plugin in v6.8.0+.
+
+  When a workflow step calls `github.rest.actions.createRepoVariable()`,
+  `github.rest.actions.listRepoVariables()`, `github.rest.actions.listEnvironmentVariables()`,
+  or other Variables API methods, these functions simply do not exist in the bundled octokit
+  inside `github-script@v6`. JavaScript returns `undefined` when accessing the property, and
+  attempting to call it throws a `TypeError: X is not a function` that fails the step immediately.
+
+  The workflow log shows the TypeError and a non-zero exit code. The confusing part is that the
+  GitHub REST API itself fully supports these endpoints — the failure is an action version issue,
+  not an API permission or token scope issue.
+fix: |
+  Upgrade to `actions/github-script@v7`, which ships with a significantly newer version of
+  `@octokit/plugin-rest-endpoint-methods` that includes the Variables API and all other
+  endpoints added since 2023. As a workaround when staying on v6, use `github.request()`
+  with the raw REST endpoint path to call any API method directly, bypassing the typed wrapper.
+fix_code:
+  - language: yaml
+    label: "Upgrade to github-script@v7 (recommended)"
+    code: |
+      - uses: actions/github-script@v7   # v7 ships updated @octokit/plugin-rest-endpoint-methods
+        with:
+          script: |
+            await github.rest.actions.createRepoVariable({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              name: 'MY_VAR',
+              value: 'my-value'
+            });
+  - language: yaml
+    label: "Workaround for v6: use github.request() with raw REST path"
+    code: |
+      - uses: actions/github-script@v6
+        with:
+          script: |
+            // Use github.request() directly — bypasses the typed wrapper
+            await github.request('POST /repos/{owner}/{repo}/actions/variables', {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              name: 'MY_VAR',
+              value: 'my-value'
+            });
+
+            // List variables example
+            const { data } = await github.request(
+              'GET /repos/{owner}/{repo}/actions/variables',
+              { owner: context.repo.owner, repo: context.repo.repo }
+            );
+            console.log(data.variables);
+prevention:
+  - "Pin to `actions/github-script@v7` or later for any workflow using Variables API or other endpoints added after mid-2022"
+  - "When adding a new `github.rest.*` call, verify the method exists in the action version's bundled octokit before deploying"
+  - "Use `github.request()` with raw REST paths as a version-independent fallback for any endpoint call"
+docs:
+  - url: "https://github.com/actions/github-script/issues/345"
+    label: "actions/github-script#345 — octokit.rest.actions not available"
+  - url: "https://github.com/actions/github-script/releases/tag/v7.0.0"
+    label: "actions/github-script v7.0.0 release — updated @octokit/plugin-rest-endpoint-methods"
+  - url: "https://octokit.github.io/rest.js/v18/#actions"
+    label: "Octokit REST.js — actions endpoints reference"

package/errors/runner-environment/macos-13-deprecation-brownout.yml

@@ -0,0 +1,93 @@
+id: runner-environment-050
+title: "macOS 13 Runner Deprecated and Removed — Jobs Fail During Brownout Windows"
+category: runner-environment
+severity: error
+tags:
+  - macos-13
+  - runner-deprecation
+  - brownout
+  - migration
+  - macos-14
+  - runner-images
+patterns:
+  - regex: "The label 'macos-13' is not present on any runner"
+    flags: "i"
+  - regex: "No runner matching the specified labels was found.*macos-13"
+    flags: "i"
+  - regex: "macos-13.*deprecated|deprecated.*macos-13"
+    flags: "i"
+  - regex: "Request 'macos-13'.*could not be satisfied"
+    flags: "i"
+error_messages:
+  - "The label 'macos-13' is not present on any runner"
+  - "No runner matching the specified labels was found: macos-13"
+root_cause: |
+  GitHub deprecated and eventually removed the `macos-13` and `macos-13-xlarge` runner labels
+  in 2025 (announced in runner-images#13046). GitHub applied brownout windows before full removal:
+  during these windows the macOS 13 label is temporarily unavailable and any job requesting it
+  either hangs waiting for a runner or immediately fails with a "label not present" error.
+
+  After the final retirement date, the label is gone entirely. The retirement schedule followed
+  the same brownout → retirement pattern used for Ubuntu 20.04 and Windows 2019.
+
+  Common workflows affected:
+  - iOS/macOS app CI that pinned to `macos-13` for Xcode 15 compatibility
+  - Workflows that avoided `macos-14` (Apple Silicon) due to architecture differences
+  - Repos that never updated after initially picking `macos-13` at release time
+fix: |
+  Migrate `runs-on: macos-13` to a supported macOS label. Recommended choices:
+
+  - `macos-latest` — automatically follows GitHub's current default (tracks major version bumps)
+  - `macos-15` — macOS 15 Sequoia, ARM64 (Apple Silicon), Xcode 16+
+  - `macos-14` — macOS 14 Sonoma, ARM64 (Apple Silicon), well-supported
+  - `macos-15-intel` or `macos-14-large` — for workflows requiring x86-64 architecture
+
+  Note: macOS 14+ runners are ARM64 by default. If your build toolchain requires x86-64, use
+  an explicitly-labeled Intel variant. Test Homebrew packages, build scripts, and any binary
+  tools on the new architecture before fully migrating.
+fix_code:
+  - language: yaml
+    label: "Migrate from macos-13 to macos-15 (ARM64)"
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: macos-13
+          runs-on: macos-15   # macOS 15 Sequoia, ARM64, Xcode 16+
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'
+  - language: yaml
+    label: "Use macos-latest for automatic version tracking"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # tracks GitHub's current recommended version
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: swift build
+  - language: yaml
+    label: "Matrix testing across macOS versions"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [macos-14, macos-15]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: swift test
+prevention:
+  - "Subscribe to runner-images announcements to learn about deprecation timelines before brownout windows start."
+  - "Use `macos-latest` when your workflow does not require a specific OS version — it automatically follows GitHub's supported default."
+  - "Test on the new image in a feature branch before the official retirement date to catch Xcode, SDK, or toolchain differences."
+  - "For x86-64-specific toolchains, check whether an Intel variant label is available before the migration deadline."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13046"
+    label: "runner-images#13046 — macOS 13 deprecation and brownout schedule"
+  - url: "https://github.com/actions/runner-images/releases"
+    label: "runner-images releases — current supported macOS image versions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs — supported GitHub-hosted runner labels"