@htekdev/actions-debugger 1.0.23 → 1.0.25

package/errors/permissions-auth/github-token-contents-write-missing-git-push.yml

@@ -0,0 +1,117 @@
+id: permissions-auth-025
+title: "GITHUB_TOKEN Missing contents:write — git push Returns 403 Write Access Not Granted"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - contents-write
+  - git-push
+  - 403
+  - permissions-block
+  - auto-commit
+  - write-access
+patterns:
+  - regex: "remote: Write access to repository not granted"
+    flags: "i"
+  - regex: "error: failed to push some refs"
+    flags: "i"
+  - regex: "refusing to allow.*GitHub Actions.*to create or update workflow"
+    flags: "i"
+  - regex: "HttpError: Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "remote: Write access to repository not granted."
+  - "error: failed to push some refs to 'https://github.com/owner/repo.git'"
+  - "fatal: unable to access 'https://github.com/owner/repo.git/': The requested URL returned error: 403"
+  - "Resource not accessible by integration"
+root_cause: |
+  The GITHUB_TOKEN is scoped by the `permissions:` block on the workflow or job. When any
+  `permissions:` block is present, all unspecified permissions are set to `none` (not to their
+  defaults). If `contents: write` is not explicitly granted, any `git push`, `git commit`, or
+  REST API call that writes to the repository will be rejected with HTTP 403 "Write access to
+  repository not granted."
+
+  Three common situations:
+
+  1. **Minimal permissions block** — the workflow declares `permissions: read-all` or lists
+     specific permissions (e.g., `pull-requests: write`) but omits `contents: write`. Any
+     subsequent git push fails with 403.
+
+  2. **Inherited restrictive org policy** — the organization sets the default token permission
+     to "read repository contents" (Settings → Actions → General → Workflow permissions). Without
+     an explicit `contents: write` in the workflow, the token cannot push.
+
+  3. **Fine-grained token in workflow context** — a PAT or GitHub App token is used for checkout
+     but the GITHUB_TOKEN (still the effective token for `git push`) lacks write access.
+
+  This is distinct from `permissions-auth-017` (empty `permissions: {}` block removing
+  `contents: read` and breaking checkout). This pattern specifically affects git write operations
+  and REST API calls that create or update repository content.
+fix: |
+  Add `contents: write` to the permissions block on the job or workflow where the push occurs.
+  Grant the narrowest scope needed — prefer job-level `permissions:` over workflow-level to
+  limit the blast radius.
+
+  If the org policy sets the default to "read-only", every workflow that writes to the repo
+  must explicitly declare `contents: write`.
+fix_code:
+  - language: yaml
+    label: "Add contents:write at the job level (preferred — narrowest scope)"
+    code: |
+      jobs:
+        auto-commit:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write   # ← required for git push / creating commits via API
+          steps:
+            - uses: actions/checkout@v4
+            - name: Bump version and push
+              run: |
+                git config user.name  "github-actions[bot]"
+                git config user.email "github-actions[bot]@users.noreply.github.com"
+                npm version patch --no-git-tag-version
+                git add package.json
+                git commit -m "chore: bump version [skip ci]"
+                git push
+  - language: yaml
+    label: "Org default is read-only — always set explicit contents:write for push workflows"
+    code: |
+      # When Settings → Actions → General → Workflow permissions = "Read repository contents and packages"
+      # EVERY workflow that pushes must declare contents: write:
+
+      permissions:
+        contents: write       # required for git push, release creation, branch creation
+        pull-requests: write  # only if the workflow also comments on PRs
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Create release
+              run: gh release create "${{ github.ref_name }}" --generate-notes
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Debug: print effective token permissions before failing"
+    code: |
+      - name: Check token permissions
+        run: |
+          gh api /repos/${{ github.repository }} --jq '.permissions'
+          gh auth status
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Always add `contents: write` to any job that does `git push`, `git tag`, creates releases, or writes files via the GitHub API."
+  - "Set the organization default to 'Read and write' only when necessary; otherwise document that all push workflows must declare `contents: write`."
+  - "Use job-level `permissions:` blocks instead of workflow-level to minimize token scope."
+  - "Add a permissions comment near the `permissions:` block listing what each grant is needed for, so future maintainers don't accidentally remove it."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token"
+    label: "GitHub Docs: Controlling permissions for GITHUB_TOKEN"
+  - url: "https://stackoverflow.com/questions/79437803/git-commit-in-github-actions-workflow-failing-write-access-to-repository-not"
+    label: "SO#79437803 — git commit failing: Write access to repository not granted, 403"
+  - url: "https://stackoverflow.com/questions/79471500/github-actions-authentication-failed-for-pushing-to-repository"
+    label: "SO#79471500 — Authentication failed for pushing to repository"
+  - url: "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository"
+    label: "GitHub Docs: Setting GITHUB_TOKEN default permissions"

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"