@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/permissions-auth/org-actions-policy-blocks-unapproved-action.yml

@@ -0,0 +1,106 @@
+id: permissions-auth-026
+title: "Org Actions Policy Blocks Workflow — Action Not in Allowlist"
+category: permissions-auth
+severity: error
+tags:
+  - org-policy
+  - allowlist
+  - action-policy
+  - enterprise
+  - third-party-actions
+  - settings
+  - admin
+patterns:
+  - regex: "is not allowed to run\\. If you believe this action should be allowed"
+    flags: "i"
+  - regex: "'[^']+' is not allowed"
+    flags: "i"
+  - regex: "Action .+ is not allowed by the organization"
+    flags: "i"
+  - regex: "This action is not allowed"
+    flags: "i"
+error_messages:
+  - "Error: Action 'actions/setup-node@v4' is not allowed. If you believe this action should be allowed, ask your GitHub org admin to approve it."
+  - "'owner/action@v2' is not allowed to run. If you believe this action should be allowed, ask your organization's GitHub Actions admin to allow it."
+  - "This action is not allowed because your organization has restricted which actions can be used in workflows."
+root_cause: |
+  GitHub organizations and enterprises can restrict which GitHub Actions are permitted
+  to run via Settings → Actions → General → "Allow select actions and reusable workflows".
+  When this policy is enabled, any workflow referencing an action not on the approved list
+  fails immediately at queue time with "is not allowed" — no job steps execute.
+
+  Three policy modes exist:
+  1. **Allow all actions** (default) — no restrictions.
+  2. **Allow GitHub-created actions only** — only `actions/*`, `github/*` etc. permitted.
+  3. **Allow select actions** — explicit allowlist + optional pattern-matching rules.
+
+  Common failure scenarios:
+  - A developer adds a popular marketplace action (e.g., `slackapi/slack-github-action`)
+    that hasn't been pre-approved by the org admin.
+  - A new CI requirement introduces a third-party security scanner that isn't allowlisted.
+  - An internal action is referenced before the admin adds the pattern to the allowlist.
+  - After an org migration, the allowlist from the source org is not reproduced in the
+    target org.
+
+  The error surfaces in the "Set up job" phase, before any workflow steps run, making
+  it look like a runner or permissions issue rather than an org policy issue. Developers
+  without org admin access cannot fix this themselves.
+fix: |
+  An organization admin must update the Actions policy:
+
+  Settings → Actions → General → "Allow select actions and reusable workflows"
+
+  Options:
+  1. **Allowlist specific actions**: Add the required action pattern (e.g.,
+     `slackapi/slack-github-action@*`) to the allowed list.
+  2. **Allow GitHub-owned and verified creator actions**: Enables all verified marketplace
+     actions without individual approval.
+  3. **Allow all actions**: Remove policy restrictions entirely (not recommended for
+     security-sensitive orgs).
+
+  For enterprise-managed repos, the enterprise-level policy may override org-level
+  settings — check Settings → Enterprise → Policies → Actions.
+fix_code:
+  - language: yaml
+    label: "Temporary workaround — pin action SHA to bypass tag-based allowlist patterns"
+    code: |
+      # If the org allowlist accepts SHA-pinned actions:
+      # Replace the version tag with the commit SHA of the same version.
+      # (Some org policies allow SHA-pinned actions even if the tag isn't approved.)
+
+      steps:
+        # Instead of: uses: slackapi/slack-github-action@v1.24.0
+        - uses: slackapi/slack-github-action@6c661ce58804a1a20f6dc5fbee7f0381b469e001  # v1.24.0
+          with:
+            channel-id: 'C12345'
+  - language: yaml
+    label: "Use a GitHub-owned alternative when allowlist blocks third-party action"
+    code: |
+      # Example: replace a third-party notification action with curl + GITHUB_TOKEN
+      - name: Post to Slack via webhook (no third-party action needed)
+        run: |
+          curl -X POST "${{ secrets.SLACK_WEBHOOK_URL }}" \
+            -H 'Content-type: application/json' \
+            --data '{"text":"Deploy finished: ${{ github.run_url }}"}'
+  - language: yaml
+    label: "Check which actions are permitted before adding new dependencies"
+    code: |
+      # There is no API to check allowlist programmatically — use the UI:
+      # Settings → Actions → General → "Allowed actions and reusable workflows"
+      # Or check via REST API (org admins only):
+      # GET /orgs/{org}/actions/permissions/selected-actions
+prevention:
+  - "Document the org's action allowlist policy in your CONTRIBUTING.md or developer onboarding guide so developers know to request approval before adding new actions."
+  - "Use Dependabot for GitHub Actions updates — approved actions stay approved when bumping minor/patch versions if the org uses wildcard patterns (e.g., `slackapi/slack-github-action@*`)."
+  - "Prefer GitHub-owned actions (`actions/*`, `github/*`) and verified creator actions to minimize allowlist friction."
+  - "Create an internal Slack/Teams channel or GitHub Discussion where developers can request new action approvals from org admins."
+  - "Use the GitHub REST API (`GET /orgs/{org}/actions/permissions/selected-actions`) to audit and document the current allowlist for new-member onboarding."
+docs:
+  - url: "https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization"
+    label: "GitHub Docs: Disabling or limiting GitHub Actions for your organization"
+  - url: "https://docs.github.com/en/rest/actions/permissions"
+    label: "GitHub REST API: Actions Permissions"
+  - url: "https://github.blog/changelog/2026-02-05-github-actions-early-february-2026-updates/"
+    label: "GitHub Changelog: Actions early February 2026 updates (action allowlisting)"
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise"
+    label: "GitHub Docs: Enforcing GitHub Actions policies in your enterprise"

package/errors/runner-environment/codeql-action-v2-deprecated.yml

@@ -0,0 +1,110 @@
+id: runner-environment-061
+title: "CodeQL Action v1/v2 Deprecated — Hard Failure with Upgrade Required Message"
+category: runner-environment
+severity: error
+tags:
+  - codeql
+  - code-scanning
+  - deprecated
+  - v2
+  - v3
+  - security
+  - breaking-change
+patterns:
+  - regex: "CodeQL Action major versions v1 and v2 have been deprecated"
+    flags: "i"
+  - regex: "Please update all occurrences of the CodeQL Action in your workflow files to v3"
+    flags: "i"
+  - regex: "github/codeql-action/.*@v[12]\\b"
+    flags: "i"
+error_messages:
+  - "Error: CodeQL Action major versions v1 and v2 have been deprecated. Please update all occurrences of the CodeQL Action in your workflow files to v3. For more information, see https://github.blog/changelog/2025-01-10-code-scanning-codeql-action-v2-is-now-deprecated/"
+  - "CodeQL Action v2 is now deprecated. Upgrade to v3."
+root_cause: |
+  GitHub retired CodeQL Action major versions v1 and v2 in January 2025. After the
+  retirement date, any workflow referencing `github/codeql-action/*@v1` or
+  `github/codeql-action/*@v2` produces a hard failure with the above error message
+  and does NOT perform code scanning.
+
+  The CodeQL action family includes multiple steps that must ALL be updated together:
+  - `github/codeql-action/init@v2`
+  - `github/codeql-action/autobuild@v2`
+  - `github/codeql-action/analyze@v2`
+  - `github/codeql-action/upload-sarif@v2`
+  - `github/codeql-action/resolve-environment@v2`
+
+  Missing even one of these (leaving it at `@v2` while updating others to `@v3`)
+  causes the workflow to fail. Repos created before 2024 using the default
+  GitHub-provided Code Scanning setup workflow are the most common source of
+  stale v2 references.
+
+  This is distinct from the generic `deprecated-action-version-auto-rejected` pattern
+  (runner-environment-037) which covers specific minor/patch versions of actions/cache,
+  actions/checkout, etc. The CodeQL deprecation applies to entire major versions v1 and v2
+  and produces a specific, different error message.
+fix: |
+  Replace every `github/codeql-action/*@v2` (and `@v1`) reference in all workflow files
+  with the corresponding `@v3` tag. All steps in the CodeQL workflow must be updated
+  together — a partial update (e.g., `init@v3` but `analyze@v2`) will still fail.
+
+  After updating, verify the workflow runs successfully by checking the Actions tab
+  and the Security → Code Scanning alerts page.
+fix_code:
+  - language: yaml
+    label: "Updated CodeQL workflow using v3 (all steps)"
+    code: |
+      name: "CodeQL Analysis"
+      on:
+        push:
+          branches: ["main"]
+        pull_request:
+          branches: ["main"]
+        schedule:
+          - cron: '0 6 * * 1'
+
+      jobs:
+        analyze:
+          name: Analyze (${{ matrix.language }})
+          runs-on: ubuntu-latest
+          permissions:
+            actions: read
+            contents: read
+            security-events: write
+
+          strategy:
+            matrix:
+              language: ['javascript', 'python']
+
+          steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+
+            - name: Initialize CodeQL
+              uses: github/codeql-action/init@v3          # ← was @v2
+              with:
+                languages: ${{ matrix.language }}
+
+            - name: Autobuild
+              uses: github/codeql-action/autobuild@v3     # ← was @v2
+
+            - name: Perform CodeQL Analysis
+              uses: github/codeql-action/analyze@v3       # ← was @v2
+              with:
+                category: "/language:${{ matrix.language }}"
+  - language: yaml
+    label: "Bulk-find stale v2 references (shell one-liner)"
+    code: |
+      # Run from repo root to find all @v1 or @v2 codeql-action references:
+      # grep -rn "codeql-action/.*@v[12]" .github/workflows/
+prevention:
+  - "Use Dependabot for GitHub Actions to automatically open PRs when actions release new major versions."
+  - "Enable the 'Actions' section in Dependabot config (`package-ecosystem: github-actions`) for all repos with CodeQL workflows."
+  - "After any CodeQL major version update, verify Security → Code Scanning shows recent scans with no 'Tool not recognized' errors."
+  - "Search all workflow files for `codeql-action` references before major GitHub deprecation windows."
+docs:
+  - url: "https://github.blog/changelog/2025-01-10-code-scanning-codeql-action-v2-is-now-deprecated/"
+    label: "GitHub Changelog: Code scanning — CodeQL Action v2 is now deprecated (Jan 2025)"
+  - url: "https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages"
+    label: "GitHub Docs: CodeQL code scanning for compiled languages"
+  - url: "https://github.com/github/codeql-action/releases"
+    label: "github/codeql-action Releases — v3 changelog"

package/errors/runner-environment/macos-26-openssl-3-system-library-breaking.yml

@@ -0,0 +1,114 @@
+id: runner-environment-070
+title: "macOS 26 Upgrades OpenSSL from 1.1.1 to 3.x — Hardcoded openssl@1.1 Paths Break"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - openssl
+  - macos-26
+  - runner-image
+  - breaking-change
+  - homebrew
+patterns:
+  - regex: "Library not loaded.*openssl@1\\.1.*libssl\\.1\\.1\\.dylib"
+    flags: "i"
+  - regex: "ld.*library not found.*-lssl|cannot find.*libssl\\.1\\.1"
+    flags: "i"
+  - regex: "openssl@1\\.1.*not installed|brew.*openssl@1\\.1.*no longer"
+    flags: "i"
+  - regex: "Could not find OpenSSL|ssl.*version.*mismatch.*1\\.1"
+    flags: "i"
+  - regex: "OpenSSL 1\\.1\\.1.*required.*OpenSSL 3"
+    flags: "i"
+error_messages:
+  - "Library not loaded: /usr/local/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "Library not loaded: /opt/homebrew/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "ld: library not found for -lssl (referenced from build target)"
+  - "Could not find a package configuration file provided by 'OpenSSL'"
+  - "Could not link to OpenSSL library. Please install OpenSSL."
+root_cause: |
+  When macos-latest migrates to macos-26 (rolling out June 15 through July 15, 2026),
+  the system OpenSSL jumps from OpenSSL 1.1.1w (the last 1.x release, now EOL)
+  to OpenSSL 3.6.2. This is a major version change with breaking ABI differences.
+
+  Any workflow that hardcodes openssl@1.1 Homebrew paths or links against the
+  1.1.x shared libraries will fail because:
+
+  - Homebrew's openssl@1.1 formula is deprecated on macOS 26
+  - The shared library /opt/homebrew/opt/openssl@1.1/lib/libssl.1.1.dylib
+    no longer exists; it is replaced by openssl@3
+  - PKG_CONFIG_PATH and LDFLAGS pointing to openssl@1.1 resolve to nothing
+
+  Common breakage surfaces:
+  - Ruby gems with native extensions (openssl gem links against system OpenSSL)
+  - Python packages (pyOpenSSL, cryptography) that link against 1.x path
+  - CMake projects using find_package(OpenSSL) finding incompatible version
+  - Homebrew formulas linking transitively against openssl@1.1
+
+  Source: runner-images#14167 — macOS 15 vs macOS 26 software diff shows
+  OpenSSL jumps from 1.1.1w to 3.6.2.
+fix: |
+  Replace all openssl@1.1 references with openssl@3 (installed by default on macOS 26).
+
+  For Homebrew-based builds, use dynamic path detection:
+    OPENSSL_DIR=$(brew --prefix openssl@3)
+    export LDFLAGS="-L${OPENSSL_DIR}/lib"
+    export PKG_CONFIG_PATH="${OPENSSL_DIR}/lib/pkgconfig"
+
+  For Ruby gem compilation:
+    bundle config build.openssl --with-openssl-dir=$(brew --prefix openssl@3)
+
+  For CMake, pass OPENSSL_ROOT_DIR:
+    cmake -DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3) ..
+fix_code:
+  - language: yaml
+    label: "Dynamic OpenSSL path — works on both macOS 15 and macOS 26"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set OpenSSL environment variables
+              run: |
+                OPENSSL_PREFIX=$(brew --prefix openssl)
+                echo "OPENSSL_DIR=$OPENSSL_PREFIX" >> $GITHUB_ENV
+                echo "LDFLAGS=-L$OPENSSL_PREFIX/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$OPENSSL_PREFIX/include" >> $GITHUB_ENV
+                echo "PKG_CONFIG_PATH=$OPENSSL_PREFIX/lib/pkgconfig" >> $GITHUB_ENV
+
+            - name: Build project
+              run: cmake -B build -DOPENSSL_ROOT_DIR=$OPENSSL_DIR && cmake --build build
+  - language: yaml
+    label: "Ruby bundler — configure openssl@3 for native extension builds"
+    code: |
+      jobs:
+        ruby-build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.4'
+                bundler-cache: true
+
+            - name: Configure OpenSSL for bundler
+              run: |
+                OPENSSL_DIR=$(brew --prefix openssl@3)
+                bundle config build.openssl --with-openssl-dir=$OPENSSL_DIR
+
+            - name: Install gems
+              run: bundle install
+prevention:
+  - "Never hardcode openssl@1.1 paths — always use $(brew --prefix openssl) dynamically."
+  - "Test your macOS workflows on macos-26 before macos-latest migrates (June 15 to July 15, 2026)."
+  - "Use macos-15 label to pin to the older image while migrating OpenSSL dependencies."
+  - "For language setup actions, ensure you use recent versions that handle OpenSSL 3 automatically."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026 (includes OpenSSL diff)"
+  - url: "https://www.openssl.org/news/changelog.html"
+    label: "OpenSSL 3.x Changelog"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners"

package/errors/runner-environment/macos-26-ruby-34-default-upgrade.yml

@@ -0,0 +1,114 @@
+id: runner-environment-072
+title: "macOS 26 Upgrades Default Ruby from 3.3 to 3.4 — Native Gem ABI Breaks"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - ruby
+  - macos-26
+  - runner-image
+  - breaking-change
+  - native-extensions
+patterns:
+  - regex: 'incompatible library version.*\.bundle|LoadError.*incompatible library'
+    flags: "i"
+  - regex: 'ruby.*3\.3.*required.*3\.4|Gem.*compiled.*Ruby 3\.3.*running.*3\.4'
+    flags: "i"
+  - regex: "Bundler.*RUBY_VERSION.*mismatch|native extension.*wrong Ruby version"
+    flags: "i"
+  - regex: 'Error loading.*\.bundle.*built for Ruby 3\.3'
+    flags: "i"
+error_messages:
+  - "LoadError: incompatible library version - /path/to/gem.bundle (expected 3.3, got 3.4)"
+  - "Bundler::GemNotFound: Could not find gem 'pg (>= 0) ruby' in locally installed gems"
+  - "An error occurred while installing nokogiri, and Bundler cannot continue."
+  - "Your Ruby version is 3.4.x, but your Gemfile specified 3.3.x"
+root_cause: |
+  When macos-latest migrates to macos-26 (June 15 through July 15, 2026), the default
+  system Ruby version jumps from 3.3.11 to 3.4.9. This is a minor Ruby version change
+  but it breaks any workflow that:
+
+  1. Has a Gemfile or .ruby-version pinning Ruby 3.3.x
+  2. Uses cached gem bundles built against Ruby 3.3's C ABI (native extensions
+     like nokogiri, pg, mysql2, ffi compile to .bundle files tied to the Ruby ABI)
+  3. Hardcodes RUBY_VERSION in build scripts or Gemfile.lock references
+
+  Ruby native extensions (.bundle files) are ABI-specific — gems compiled against
+  Ruby 3.3 cannot be loaded by Ruby 3.4 and vice versa. If a workflow caches
+  bundled gems from a prior run on macos-15 (Ruby 3.3) and restores them on
+  macos-26 (Ruby 3.4), native extension gems will fail to load.
+
+  Source: runner-images#14167 — macOS 15 vs macOS 26 software diff shows Ruby
+  jumping from 3.3.11 to 3.4.9.
+fix: |
+  Option 1 — Use ruby/setup-ruby to pin an explicit Ruby version (recommended):
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.3'  # or '3.4' to target the new default
+        bundler-cache: true
+
+  Option 2 — Add .ruby-version file to your repo specifying the target Ruby version.
+  setup-ruby will read this automatically.
+
+  Option 3 — Update your Gemfile to remove Ruby version constraint or bump it to 3.4:
+    # In Gemfile, remove or update:
+    # ruby '3.3'  <- remove or change to '3.4'
+
+  For cache invalidation: if you use actions/cache for bundler, include the Ruby
+  version in the cache key:
+    key: gems-${{ runner.os }}-ruby-${{ env.RUBY_VERSION }}-${{ hashFiles('**/Gemfile.lock') }}
+fix_code:
+  - language: yaml
+    label: "Pin Ruby version with setup-ruby (cross-image safe)"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                # Pin explicitly — do not rely on runner default Ruby
+                ruby-version: '3.4'
+                bundler-cache: true
+
+            - name: Run tests
+              run: bundle exec rspec
+
+  - language: yaml
+    label: "Cache key including Ruby version to avoid ABI mismatch"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.4'
+
+            - name: Cache bundler gems
+              uses: actions/cache@v4
+              with:
+                path: vendor/bundle
+                # Include Ruby version in cache key to prevent ABI mismatch
+                key: gems-${{ runner.os }}-ruby-${{ env.RUBY_VERSION }}-${{ hashFiles('**/Gemfile.lock') }}
+                restore-keys: |
+                  gems-${{ runner.os }}-ruby-${{ env.RUBY_VERSION }}-
+
+            - name: Install gems
+              run: bundle install --path vendor/bundle
+prevention:
+  - "Always use ruby/setup-ruby with an explicit ruby-version — never rely on the runner's default Ruby."
+  - "Include the Ruby version in bundler cache keys to prevent loading native gems built for a different Ruby ABI."
+  - "Add a .ruby-version file to your repository to make the intended Ruby version visible and enforceable."
+  - "Test on macos-26 before macos-latest migrates to catch Ruby 3.3 to 3.4 incompatibilities early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026 (includes Ruby version diff)"
+  - url: "https://github.com/ruby/setup-ruby"
+    label: "ruby/setup-ruby action"
+  - url: "https://www.ruby-lang.org/en/news/2024/12/25/ruby-3-4-0-released/"
+    label: "Ruby 3.4.0 Release Notes"

package/errors/runner-environment/macos-26-xcode-default-265-pin-required.yml

@@ -0,0 +1,99 @@
+id: runner-environment-071
+title: "macOS 26 Default Xcode Switches to 26.5 on June 8 2026 — Unpin to Fix"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcode
+  - macos-26
+  - runner-image
+  - breaking-change
+  - ios
+patterns:
+  - regex: 'Xcode.*26\.4\.1.*not found|xcode.*version.*26\.4.*unavailable'
+    flags: "i"
+  - regex: 'your project.*not compatible.*Xcode 26\.5|requires Xcode.*26\.4'
+    flags: "i"
+  - regex: 'xcodebuild.*error.*incompatible.*project|DT_TOOLCHAIN.*not found.*26\.5'
+    flags: "i"
+  - regex: 'error.*The iOS Simulator.*26\.1.*required.*26\.5'
+    flags: "i"
+error_messages:
+  - "xcodebuild: error: The project requires Xcode 26.4.1, but the currently selected Xcode version is 26.5."
+  - "error: DT_TOOLCHAIN_DIR cannot be used to evaluate TOOLCHAIN_DIR. Use TOOLCHAINS setting instead."
+  - "Unable to boot the Simulator. The request to boot 'iOS 26.1 Simulator' was denied because the destination is incompatible with this version of Xcode."
+root_cause: |
+  Starting June 8, 2026 (rolling out over 2-4 days), GitHub is changing the default
+  Xcode on macOS-26 runners from Xcode 26.4.1 to Xcode 26.5. Workflows running on
+  macos-26 or macos-latest (after the macos-latest migration completes) that do not
+  explicitly pin an Xcode version will automatically get Xcode 26.5.
+
+  Xcode 26.5 is a new major release and may introduce build incompatibilities:
+  - Project files referencing deprecated Xcode 26.4 APIs
+  - iOS/macOS Simulator runtimes that only match Xcode 26.4.1
+  - Swift toolchain behavior differences between 26.4.1 and 26.5
+  - Build setting migrations required by the new Xcode version
+
+  Source: runner-images#14172 — official GitHub announcement for macOS 26 Xcode
+  default change.
+fix: |
+  Pin your Xcode version explicitly using either:
+
+  Option 1 — sudo xcode-select (no extra action required):
+    sudo xcode-select -s "/Applications/Xcode_26.4.1.app"
+
+  Option 2 — maxim-lobanov/setup-xcode action:
+    - uses: maxim-lobanov/setup-xcode@v1
+      with:
+        xcode-version: '26.4.1'
+
+  To list available Xcode versions on macos-26 runners, check the official
+  runner image documentation at:
+  https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md#xcode
+fix_code:
+  - language: yaml
+    label: "Pin Xcode version using setup-xcode action"
+    code: |
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Select Xcode version
+              uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.4.1'
+
+            - name: Build iOS app
+              run: xcodebuild -project MyApp.xcodeproj -scheme MyApp -sdk iphonesimulator build
+
+  - language: yaml
+    label: "Pin Xcode version using xcode-select directly"
+    code: |
+      jobs:
+        build-ios:
+          runs-on: macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Pin Xcode 26.4.1
+              run: sudo xcode-select -s "/Applications/Xcode_26.4.1.app"
+
+            - name: Verify Xcode version
+              run: xcodebuild -version
+
+            - name: Build
+              run: xcodebuild -scheme MyApp build
+prevention:
+  - "Always pin Xcode version explicitly on macOS runners — never rely on the default."
+  - "Use maxim-lobanov/setup-xcode@v1 with a specific xcode-version to make version changes visible in git diff."
+  - "Subscribe to runner-images announcements for advance notice of Xcode default version changes."
+  - "Audit your workflows for hardcoded Xcode version paths before macos-latest migrates to macos-26."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14172"
+    label: "GitHub Announcement: Default Xcode on macOS 26 will be set to 26.5 on 2026-06-08"
+  - url: "https://github.com/maxim-lobanov/setup-xcode"
+    label: "maxim-lobanov/setup-xcode action"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md#xcode"
+    label: "macOS 26 arm64 runner image README — available Xcode versions"

package/errors/runner-environment/macos-latest-label-switches-to-macos26.yml

@@ -0,0 +1,127 @@
+id: runner-environment-064
+title: "macos-latest Label Switching to macOS 26 — Toolchain and Brew Package Changes"
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - macos-latest
+  - macos-26
+  - runner-label
+  - homebrew
+  - toolchain
+  - migration
+patterns:
+  - regex: "macos.*26.*not supported"
+    flags: "i"
+  - regex: "No such file or directory.*clang|clang.*not found"
+    flags: "i"
+  - regex: "dyld.*Library not loaded"
+    flags: "i"
+  - regex: "Error: Cannot install in Homebrew on macOS.*without Command Line Tools"
+    flags: "i"
+  - regex: "macos-latest.*macos-26"
+    flags: "i"
+error_messages:
+  - "clang: error: no such file or directory"
+  - "dyld[12345]: Library not loaded: /usr/local/lib/libssl.1.1.dylib"
+  - "Error: Your CLT does not support macOS 26."
+  - "xcrun: error: SDK 'iphoneos' cannot be located"
+root_cause: |
+  Starting June 15, 2026, the `macos-latest` runner label is being migrated
+  from macOS 15 (Sequoia) to macOS 26 (runner-images#14167). The rollout
+  runs through July 15, 2026. Workflows pinned to `macos-latest` without
+  testing on macOS 26 may encounter failures from toolchain and package
+  differences between the two OS versions.
+
+  Key differences in macOS 26 runner images compared to macOS 15:
+
+  1. **Homebrew LLVM version bump**: LLVM jumped from 18 to 20 on macOS 26.
+     Hardcoded paths like `/opt/homebrew/opt/llvm@18/bin/clang` or env vars
+     referencing `llvm@18` binaries fail. POCO and other libraries built
+     against LLVM 18 ABI may link incorrectly.
+
+  2. **macOS SDK changes**: macOS 26 uses a newer Xcode and SDK toolchain.
+     Libraries and headers that existed in macOS 15 SDK may have moved,
+     been renamed, or removed under the macOS 26 (Tahoe) SDK.
+
+  3. **Homebrew formula versions**: Many Homebrew packages have newer
+     versions on macOS 26 images than on macOS 15. Formulas with no macOS 26
+     bottle may be built from source, increasing job time significantly.
+
+  4. **System library locations**: Dynamic library paths (e.g., for OpenSSL,
+     libpq, or other system libs installed via Homebrew) may differ between
+     macOS 15 and macOS 26 as Homebrew evolves its prefix structure.
+
+  5. **Xcode simulator SDK policy**: Only the 3 latest Xcode versions retain
+     platform tools/SDKs. Workflows using older Xcode/simulator versions
+     that worked on macOS 15 may not find the expected SDK on macOS 26.
+
+  Workflows that do not pin `macos-latest` and have never tested on macOS 26
+  may start failing after the migration completes.
+fix: |
+  1. **Pin to macOS 15 temporarily**: Replace `macos-latest` with `macos-15`
+     to preserve the current behavior while you test and migrate.
+
+  2. **Test on macOS 26 before migration**: Add a matrix job with
+     `macos-26` to identify failures before `macos-latest` switches.
+
+  3. **Fix hardcoded LLVM/Clang paths**: Update any hardcoded paths like
+     `/opt/homebrew/opt/llvm@18` to use `$(brew --prefix llvm)` or install
+     the specific version you need via `brew install llvm@18`.
+
+  4. **Update Homebrew formula pins**: Check for `@version`-pinned Homebrew
+     formulas that may no longer have macOS 26 bottles and either upgrade
+     or build from source explicitly.
+
+  5. **Audit system library dependencies**: For native extensions that link
+     against system or Homebrew libraries, verify library paths with
+     `brew --prefix <lib>` at runtime rather than hardcoding them.
+fix_code:
+  - language: yaml
+    label: "Pin to macos-15 while testing macOS 26 compatibility"
+    code: |
+      jobs:
+        build:
+          # Temporarily pin to macos-15 while migration is in progress
+          # macos-latest will point to macos-26 starting June 15, 2026
+          runs-on: macos-15
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "Matrix to test both macOS 15 and 26 before migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [macos-15, macos-26]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "Use brew --prefix to resolve dynamic LLVM/library paths"
+    code: |
+      - name: Set up LLVM paths dynamically
+        run: |
+          # Instead of hardcoded /opt/homebrew/opt/llvm@18/bin/clang:
+          LLVM_PREFIX=$(brew --prefix llvm)
+          echo "CC=${LLVM_PREFIX}/bin/clang" >> $GITHUB_ENV
+          echo "CXX=${LLVM_PREFIX}/bin/clang++" >> $GITHUB_ENV
+          echo "${LLVM_PREFIX}/bin" >> $GITHUB_PATH
+prevention:
+  - "Never use macos-latest without testing the next macOS version first — GitHub announces label migrations weeks in advance in runner-images issues."
+  - "Pin to a specific macOS version (e.g., macos-15) for production workflows; use macos-latest only in exploratory or dependency-update workflows."
+  - "Avoid hardcoding Homebrew formula paths — always use `$(brew --prefix <formula>)` to resolve paths dynamically."
+  - "Run a matrix job spanning current and next macOS versions as part of your CI to catch breakage before a label migration lands."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images #14167: macos-latest will use macos-26 starting June 15, 2026"
+  - url: "https://github.blog/changelog/2026-05-14-github-actions-upcoming-image-migrations/"
+    label: "GitHub Changelog: Upcoming image migrations (May 2026)"
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images announcement: macOS 14 deprecation starting July 6, 2026"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "GitHub Docs: Standard GitHub-hosted runners — available runner labels"