@htekdev/actions-debugger 1.0.1 → 1.0.3

package/errors/caching-artifacts/artifact-download-no-artifacts-found.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-010
+title: "Artifact Download Fails — Unable to Find Any Artifacts for Run"
+category: caching-artifacts
+severity: error
+tags:
+  - artifact
+  - download
+  - run-id
+  - cross-workflow
+  - upload-artifact
+  - download-artifact
+patterns:
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "No artifacts found for run"
+    flags: "i"
+  - regex: "Error: Unable to find any artifacts"
+    flags: "i"
+error_messages:
+  - "Unable to find any artifacts for the associated workflow"
+  - "Error: Unable to find any artifacts for the associated workflow"
+  - "No artifacts were found with the provided name and filters."
+root_cause: |
+  GitHub Actions artifacts are scoped to a specific workflow run. The
+  `actions/download-artifact@v4` action (and v3 with `run-id:`) will fail with
+  "Unable to find any artifacts" when:
+
+  1. **Wrong or stale run-id** — The run ID is hard-coded or fetched from a
+     prior run that no longer has the expected artifact (artifacts expire after
+     the configured retention period, default 90 days).
+
+  2. **Upload step never ran** — The producing workflow job was cancelled, the
+     upload step was skipped due to a failed prior step, or the `if:` condition
+     on the upload step evaluated to false.
+
+  3. **Name mismatch** — The `name:` specified in `download-artifact` doesn't
+     exactly match the name used in `upload-artifact` (case-sensitive).
+
+  4. **Cross-workflow download without explicit run-id** — In v4, downloading
+     artifacts from a different workflow run requires an explicit `run-id:`.
+     Omitting it defaults to the current run, which may not have those artifacts.
+
+  Documented in GitHub Community discussion #109905.
+fix: |
+  For cross-workflow artifact sharing:
+  1. Capture the producing workflow's run-id dynamically using the GitHub REST
+     API or by passing it as a workflow_dispatch input or repository_dispatch payload.
+  2. Verify the upload step ran successfully in the producer workflow before
+     downloading in a consumer workflow.
+  3. Ensure `name:` matches exactly (case-sensitive) between upload and download.
+  4. For same-workflow jobs, omit `run-id:` — download-artifact v4 defaults to
+     the current run automatically.
+fix_code:
+  - language: yaml
+    label: "WRONG — hard-coded run-id that may be stale"
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          run-id: 12345678  # ❌ hard-coded run ID — stale if re-run or wrong workflow
+  - language: yaml
+    label: "RIGHT — same-workflow, no run-id needed"
+    code: |
+      # Job A (producer)
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output       # ✅ exact name matters
+                path: dist/
+
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output       # ✅ same name, no run-id needed for current run
+  - language: yaml
+    label: "RIGHT — cross-workflow download, run-id from API"
+    code: |
+      - name: Get latest successful run ID
+        id: get-run
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          RUN_ID=$(gh run list \
+            --workflow=build.yml \
+            --branch=main \
+            --status=success \
+            --limit=1 \
+            --json databaseId \
+            --jq '.[0].databaseId')
+          echo "run_id=$RUN_ID" >> $GITHUB_OUTPUT
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          run-id: ${{ steps.get-run.outputs.run_id }}  # ✅ dynamic run ID
+          github-token: ${{ github.token }}
+prevention:
+  - "Never hard-code run-id values — always fetch them dynamically via the GitHub API or pass them as workflow inputs."
+  - "Always verify artifact upload completed successfully before writing a consuming workflow that depends on it."
+  - "Use exact case-matching artifact names — `build-output` and `Build-Output` are different artifacts."
+  - "For same-workflow artifact sharing between jobs, omit `run-id:` entirely — it defaults to the current run."
+  - "Check artifact retention settings — artifacts expire after 90 days (public) or 400 days (private) by default."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "Storing and sharing data from a workflow"
+  - url: "https://github.com/actions/download-artifact"
+    label: "actions/download-artifact — README and cross-run download docs"
+  - url: "https://github.com/orgs/community/discussions/109905"
+    label: "GitHub Community #109905 — Unable to find any artifacts troubleshooting"
+  - url: "https://stackoverflow.com/questions/78238187/unable-to-find-any-artifacts-for-the-associated-workflow-github-actions"
+    label: "Stack Overflow — Unable to find any artifacts for the associated workflow"

package/errors/known-unsolved/workflow-rerun-limit.yml

@@ -0,0 +1,101 @@
+id: known-unsolved-007
+title: "Workflow Rerun Limit: 50 Reruns Maximum Per Workflow Run"
+category: known-unsolved
+severity: limitation
+tags:
+  - rerun
+  - retry
+  - automation
+  - limits
+  - check-suite
+patterns:
+  - regex: "exceeded.*maximum.*rerun.*limit"
+    flags: "i"
+  - regex: "rerun limit.*50"
+    flags: "i"
+  - regex: "This workflow has been rerun too many times"
+    flags: "i"
+  - regex: "maximum rerun limit.*exceeded"
+    flags: "i"
+error_messages:
+  - "This workflow has exceeded the maximum rerun limit of 50."
+  - "You have exceeded the maximum rerun limit for this workflow run."
+  - "Failed check suite: exceeded maximum rerun limit."
+root_cause: |
+  In April 2026 GitHub introduced a hard cap of 50 reruns per workflow run (combining
+  full re-runs and partial job re-runs). When the limit is hit, any subsequent rerun
+  attempt results in a failed check suite with an annotation — no partial or full rerun
+  is permitted on that run ever again.
+
+  The limit was introduced because some automation scripts were issuing hundreds of retry
+  attempts on a single workflow run, adding significant load to GitHub's infrastructure.
+
+  Common triggers of this limit:
+  - Automated retry bots (e.g. flaky-test detection scripts) that loop on `gh run rerun`
+  - CI platforms that aggressively requeue failed runs
+  - Scheduled maintenance pipelines that retry indefinitely on runner-level transient failures
+  - GitHub Apps polling and re-triggering stale check suites on long-lived PRs
+fix: |
+  There is no way to raise the 50-rerun cap — it is a hard platform limit with no bypass.
+
+  Recommended approaches:
+  1. **Fix the root cause instead of retrying** — identify and address flaky tests, network
+     timeouts, or runner instability rather than masking them with reruns.
+  2. **Create a new workflow run instead of rerunning** — close and reopen the PR, push a
+     no-op commit, or trigger `workflow_dispatch` to start a fresh run with its own 50-run
+     budget.
+  3. **Implement retry logic inside the step** — use a step-level retry loop (`for i in 1 2 3`)
+     rather than whole-workflow reruns so flakiness is contained within a single run.
+  4. **Limit automation rerun budgets** — if you operate a retry bot, add a counter check
+     (`gh run view --json runAttempt`) and stop retrying once `runAttempt >= 40` to leave
+     headroom before the limit hits.
+fix_code:
+  - language: yaml
+    label: "Step-level retry instead of whole-workflow rerun"
+    code: |
+      steps:
+        - name: Run flaky integration test (with built-in retry)
+          shell: bash
+          run: |
+            for attempt in 1 2 3; do
+              echo "Attempt $attempt of 3"
+              if npm run test:integration; then
+                echo "Tests passed on attempt $attempt"
+                exit 0
+              fi
+              echo "Attempt $attempt failed, retrying..."
+              sleep 10
+            done
+            echo "All 3 attempts failed"
+            exit 1
+  - language: yaml
+    label: "Check rerun count before auto-retrying in a workflow automation"
+    code: |
+      steps:
+        - name: Guard against rerun limit
+          shell: bash
+          run: |
+            RUN_ATTEMPT="${{ github.run_attempt }}"
+            if [ "$RUN_ATTEMPT" -ge 40 ]; then
+              echo "::error::Run attempt $RUN_ATTEMPT is near the 50-rerun limit. Stopping auto-retry."
+              exit 1
+            fi
+            echo "Run attempt $RUN_ATTEMPT — within safe retry budget"
+  - language: yaml
+    label: "Trigger a fresh run instead of rerunning (workflow_dispatch)"
+    code: |
+      # Instead of gh run rerun <run-id>, dispatch a fresh run:
+      # gh workflow run my-workflow.yml --ref main
+      # This creates a new run ID with its own 50-rerun budget.
+prevention:
+  - "Build retry logic inside steps using shell loops rather than whole-workflow reruns."
+  - "Monitor `github.run_attempt` context value; alert or stop automation at 40+ attempts."
+  - "Fix flaky tests rather than relying on reruns as the primary reliability mechanism."
+  - "If a run regularly hits >10 reruns, treat it as a reliability incident, not a normal CI pattern."
+docs:
+  - url: "https://github.blog/changelog/2026-04-10-actions-workflows-are-limited-to-50-reruns/"
+    label: "GitHub Changelog: Actions workflows are limited to 50 reruns"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "Re-running workflows and jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions"
+    label: "Workflow commands for GitHub Actions"

package/errors/permissions-auth/gcp-oidc-workload-identity-misconfigured.yml

@@ -0,0 +1,130 @@
+id: permissions-auth-008
+title: "GCP OIDC Workload Identity: Pool Path vs Provider Path / Project ID vs Number"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - gcp
+  - google-cloud
+  - workload-identity
+  - auth
+patterns:
+  - regex: "Invalid value for [\"']?audience[\"']?"
+    flags: "i"
+  - regex: "Error code invalid_request.*Invalid value for.*audience"
+    flags: "i"
+  - regex: "workloadIdentityPools.*not.*providers"
+    flags: "i"
+  - regex: "project.*number.*not.*project.*id"
+    flags: "i"
+  - regex: "OAuthError.*Invalid value for.*audience"
+    flags: "i"
+  - regex: "Error parsing credentials.*workload_identity_provider"
+    flags: "i"
+error_messages:
+  - "ERROR: gcloud crashed (OAuthError): Error code invalid_request: Invalid value for \"audience\"."
+  - "Error: google-github-actions/auth failed with: Error code invalid_request: Invalid value for \"audience\"."
+  - "The workload_identity_provider must be the full provider resource name, not the pool resource name."
+root_cause: |
+  `google-github-actions/auth` OIDC authentication fails with "Invalid value for audience"
+  when either of two common misconfiguration patterns is present:
+
+  **Mistake 1 — Pool path instead of Provider path**
+  The `workload_identity_provider` input requires the full *Provider* resource name:
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`
+
+  Many developers mistakenly supply only the *Pool* path (omitting `/providers/PROVIDER_ID`):
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID`
+
+  GCP's STS token endpoint rejects the audience because it expects the provider URI, not the pool URI.
+
+  **Mistake 2 — Project ID (string) instead of Project Number (integer)**
+  The path requires the numeric GCP project number (e.g. `123456789012`), NOT the human-readable
+  project ID (e.g. `my-gcp-project`). Workload Identity Federation does not accept project IDs.
+  Using a project ID causes the STS endpoint to return "Invalid value for audience" because the
+  resource path does not resolve to a valid identity provider.
+
+  **Mistake 3 — Missing `id-token: write` permission**
+  If `permissions.id-token` is not explicitly set to `write` at the job or workflow level,
+  GitHub will not mint an OIDC token and the auth step fails with a permissions error rather
+  than a token exchange error.
+fix: |
+  Verify the `workload_identity_provider` value against the exact format required:
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER`
+
+  Retrieve the correct value:
+    gcloud iam workload-identity-pools providers describe PROVIDER_ID \
+      --project=PROJECT_ID \
+      --location=global \
+      --workload-identity-pool=POOL_ID \
+      --format='value(name)'
+
+  Ensure `id-token: write` is set in the job permissions block.
+
+  Wait at least 5 minutes after changes to Workload Identity Pool / Provider / IAM bindings
+  before testing — these resources are eventually consistent.
+fix_code:
+  - language: yaml
+    label: "Correct workload_identity_provider format (provider path + project number)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write    # REQUIRED — grants GitHub the right to mint an OIDC token
+            contents: read
+
+          steps:
+            - uses: actions/checkout@v4
+
+            - id: auth
+              uses: google-github-actions/auth@v2
+              with:
+                # CORRECT: full provider path with numeric project number
+                workload_identity_provider: >-
+                  projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+                service_account: my-service-account@my-project.iam.gserviceaccount.com
+  - language: yaml
+    label: "Common mistake — pool path (missing /providers/...) causes audience error"
+    code: |
+      # WRONG: pool path only — gcloud crashes with "Invalid value for audience"
+      # workload_identity_provider: >-
+      #   projects/123456789012/locations/global/workloadIdentityPools/my-pool
+
+      # ALSO WRONG: project ID string instead of project number
+      # workload_identity_provider: >-
+      #   projects/my-gcp-project/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+
+      # CORRECT:
+      # workload_identity_provider: >-
+      #   projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+  - language: yaml
+    label: "Store provider path in a repository variable to avoid typos"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: google-github-actions/auth@v2
+              with:
+                # Store full provider path as a repository variable to avoid typos
+                workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
+                service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
+prevention:
+  - "Always use `gcloud iam workload-identity-pools providers describe` to copy the exact provider path."
+  - "Store the full provider path in a GitHub Actions variable (`vars.GCP_WIF_PROVIDER`) to prevent manual typos."
+  - "Use numeric project number — retrieve it with `gcloud projects describe PROJECT_ID --format='value(projectNumber)'`."
+  - "After changing Workload Identity Pool config, wait 5 minutes before testing (eventual consistency)."
+  - "Confirm `id-token: write` permission is present at job (not just workflow) level."
+docs:
+  - url: "https://github.com/google-github-actions/auth#setup"
+    label: "google-github-actions/auth: Setup and configuration"
+  - url: "https://github.com/google-github-actions/auth/blob/main/docs/TROUBLESHOOTING.md"
+    label: "google-github-actions/auth: Troubleshooting guide"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform"
+    label: "Configuring OIDC in Google Cloud Platform"
+  - url: "https://cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines"
+    label: "GCP: Workload Identity Federation with deployment pipelines"

package/errors/runner-environment/macos-14-sonoma-eol.yml

@@ -0,0 +1,89 @@
+id: runner-environment-018
+title: "macOS 14 Sonoma Runner Deprecation — EOL November 2026"
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - deprecation
+  - runner-image
+  - eol
+  - migration
+patterns:
+  - regex: "##\\[error\\]This request was rejected because.*macos-14"
+    flags: "i"
+  - regex: "Image.*macos-14.*deprecated|macos-14.*no longer supported"
+    flags: "i"
+  - regex: "The requested image.*macos-14.*not available"
+    flags: "i"
+error_messages:
+  - "##[error]This request was rejected because the runner label 'macos-14' is no longer supported."
+  - "The macOS 14 image has been retired. Please update to macos-15 or macos-latest."
+root_cause: |
+  GitHub announced the deprecation of `macOS 14 Sonoma` runner images on the following schedule:
+  - **Deprecation begins**: July 6, 2026 — longer queue times during peak hours, brownout periods
+  - **Full retirement**: November 2, 2026 — jobs using `macos-14` will fail permanently
+
+  GitHub maintains only the latest two stable macOS major versions. Since macOS 26 Tahoe is now
+  GA on GitHub Actions, macOS 14 is the oldest and must retire.
+
+  **Brownout schedule** (jobs deliberately failed during these windows to force migration):
+  - October 5, 14:00 UTC – October 6, 00:00 UTC
+  - October 12, 14:00 UTC – October 13, 00:00 UTC
+  - October 16–30, 14:00 UTC – next day 00:00 UTC (escalating weekly)
+
+  Affected labels: `macos-14`, `macos-14-large`, `macos-14-xlarge`.
+fix: |
+  Update your workflow's `runs-on` label to a supported macOS version:
+
+  | Old label | Replace with |
+  |-----------|--------------|
+  | `macos-14` | `macos-latest` or `macos-15` or `macos-26` |
+  | `macos-14-large` | `macos-latest-large` or `macos-15-large` |
+  | `macos-14-xlarge` | `macos-latest-xlarge` or `macos-15-xlarge` or `macos-26-xlarge` |
+
+  If your workflow depends on macOS 14-specific software versions (e.g., Xcode 15, older
+  Python/Ruby), test carefully against macOS 15 before switching `macos-latest`.
+  See runner-environment-017 for macOS 15 → 26 migration notes if moving to `macos-latest`.
+fix_code:
+  - language: yaml
+    label: "Migrate from macos-14 to macos-15 (conservative) or macos-latest"
+    code: |
+      jobs:
+        build:
+          # Before:
+          # runs-on: macos-14
+
+          # Conservative: macos-15 (similar software stack, no OpenSSL jump)
+          runs-on: macos-15
+
+          # OR accept latest (currently macos-26 after June 15 2026):
+          # runs-on: macos-latest
+
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Strategy matrix: test across multiple macOS versions during migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [macos-15, macos-26]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: make test
+prevention:
+  - "Subscribe to actions/runner-images GitHub Issues announcements label to receive deprecation notices well in advance."
+  - "Avoid pinning to specific macOS point versions (`macos-14`, `macos-15`) in long-lived workflows — use `macos-latest` and test proactively against the next version."
+  - "Run a matrix strategy against `macos-latest` and your pinned version to detect incompatibilities before they cause production failures."
+  - "Search your organization's workflows periodically for deprecated runner labels using: `gh search code 'runs-on: macos-14' --owner YOUR_ORG`."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13518"
+    label: "GitHub Announcement: macOS 14 Sonoma deprecation timeline"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "Supported GitHub-hosted runner labels"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner deprecation and EOL"

package/errors/runner-environment/macos-latest-to-macos-26.yml

@@ -0,0 +1,127 @@
+id: runner-environment-017
+title: "macos-latest Label Now Points to macOS 26 Tahoe"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - runner-image
+  - breaking-change
+  - openssl
+  - xcode
+  - migration
+patterns:
+  - regex: "Error opening configuration file.*openssl"
+    flags: "i"
+  - regex: "SSL_CTX_new.*failed|SSL_connect.*SYSCALL error"
+    flags: "i"
+  - regex: "Could not find Xcode.*version.*16\\.\\d"
+    flags: "i"
+  - regex: "ruby.*requires.*Ruby (2|3\\.0|3\\.1|3\\.2|3\\.3)"
+    flags: "i"
+  - regex: "dyld.*Library not loaded.*libssl\\.1\\.1"
+    flags: "i"
+error_messages:
+  - "dyld[]: Library not loaded: /usr/local/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "Could not find Xcode version '16.4'"
+  - "SSL_connect returned=1 errno=0 state=error: certificate verify failed"
+  - "Your Ruby version is 3.3.x, but your Gemfile specified ~> 3.3"
+  - "npm warn old lockfile"
+root_cause: |
+  The `macos-latest` label in GitHub Actions was migrated to point to macOS 26 Tahoe
+  beginning June 15, 2026 (completing by July 15, 2026). Previously it pointed to macOS 15
+  Sequoia. This migration includes several major software version changes that silently break
+  workflows:
+
+  - **OpenSSL**: 1.1.1w → 3.6.2 — The biggest breaking change. Many C/C++ projects,
+    Ruby gems (openssl), and Python packages that link against the system OpenSSL dynamically
+    will fail at runtime because libssl.1.1.dylib no longer ships with macOS 26.
+  - **Xcode**: Default changes from 16.4 to 26.4.1 (Xcode 26 series). Workflows pinning
+    `xcode-version: '16.4'` or relying on Clang 17 will break — Clang/LLVM jumps from 17 → 21.
+  - **Ruby**: 3.3.x → 3.4.x — Minor version bump can cause Gemfile constraint failures and
+    gem native extension compilation issues.
+  - **Node.js**: Default moves from 22 → 24 (though both images include Node 24 in cached tools).
+  - **npm**: 10.x → 11.x — Major npm version. Package-lock.json format changes possible.
+  - **Homebrew LLVM**: 18 → 20 (major version jump for workflows using `llvm@18` explicitly).
+fix: |
+  **Immediate mitigation:** Pin to `macos-15` to restore previous behavior while you migrate:
+
+  ```yaml
+  runs-on: macos-15
+  ```
+
+  **Proper fix** — address each breaking dependency:
+
+  1. **OpenSSL**: Brew-install a pinned OpenSSL version and set library paths:
+     ```bash
+     brew install openssl@1.1
+     export LDFLAGS="-L$(brew --prefix openssl@1.1)/lib"
+     export CPPFLAGS="-I$(brew --prefix openssl@1.1)/include"
+     ```
+     Or migrate to OpenSSL 3.x compatible code.
+
+  2. **Xcode**: Pin the Xcode version explicitly using `maxim-lobanov/setup-xcode`:
+     ```yaml
+     - uses: maxim-lobanov/setup-xcode@v1
+       with:
+         xcode-version: '16.4'
+     ```
+     Or migrate your project to Xcode 26.
+
+  3. **Ruby**: Update your Gemfile to accept 3.4.x (`~> 3.4`) or use `ruby/setup-ruby` to
+     pin a specific version:
+     ```yaml
+     - uses: ruby/setup-ruby@v1
+       with:
+         ruby-version: '3.3'
+     ```
+fix_code:
+  - language: yaml
+    label: "Pin to macos-15 for immediate rollback"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-15   # pinned until macos-26 migration complete
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Full macos-26 compatible workflow — pin Xcode, Ruby, and OpenSSL"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest  # now macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pin Xcode version explicitly
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.4'
+
+            # Pin Ruby if needed
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'
+                bundler-cache: true
+
+            # If OpenSSL 1.1 is needed, install and export paths
+            - name: Install OpenSSL 1.1
+              run: |
+                brew install openssl@1.1
+                echo "LDFLAGS=-L$(brew --prefix openssl@1.1)/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$(brew --prefix openssl@1.1)/include" >> $GITHUB_ENV
+prevention:
+  - "Avoid relying on `macos-latest` for builds that depend on specific system library versions (OpenSSL, LLVM). Pin to a concrete label like `macos-15`."
+  - "Subscribe to the actions/runner-images repository announcements to get advance notice of `macos-latest` label migrations."
+  - "Use `ruby/setup-ruby`, `actions/setup-node`, and `actions/setup-python` to pin language runtimes instead of relying on runner image defaults."
+  - "Test your macOS workflows against the new image early by substituting `macos-26` before the `macos-latest` migration completes."
+  - "Audit all dylib/framework dependencies — anything linking to libssl.1.1 must be migrated to OpenSSL 3.x or brew-pinned."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md"
+    label: "macOS 26 arm64 image README — full software list"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners — supported runner labels"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner image migrations"