feat: add 1 new error entry (runner-environment)

errors/runner-environment/go-1-22-1-23-removed-from-tool-cache-june-2026.yml

@@ -0,0 +1,122 @@
+id: runner-environment-508
+title: 'Go 1.22 and 1.23 Removed from Tool-Cache on June 22, 2026 — setup-go Downloads on Cache Miss'
+category: runner-environment
+severity: warning
+tags:
+  - golang
+  - setup-go
+  - tool-cache
+  - go-1-22
+  - go-1-23
+  - breaking-change
+  - runner-images
+patterns:
+  - regex: 'go: downloading.*1\.(22|23)\.'
+    flags: 'i'
+  - regex: 'setup-go.*1\.(22|23)'
+    flags: 'i'
+  - regex: 'Unable to find.*go.*1\.(22|23).*in cache'
+    flags: 'i'
+  - regex: 'go version go1\.(22|23)\.\d+ .* not found in toolcache'
+    flags: 'i'
+error_messages:
+  - 'Downloading https://storage.googleapis.com/golang/go1.22.10.linux-amd64.tar.gz'
+  - 'go: downloading 1.22.10 (linux/amd64)'
+  - 'Acquiring go 1.23.8 - downloading'
+  - 'Attempt to acquire go 1.22 from tool-cache, which is not available'
+root_cause: |
+  Starting **June 22, 2026**, GitHub removed Go versions 1.22.* and 1.23.* from the
+  tool-cache on all GitHub-hosted runner images (ubuntu-22.04, ubuntu-24.04, macos-14,
+  macos-15, macos-26, windows-2022, windows-2025, windows-2025-vs2026, windows-11-arm64,
+  and their arm variants).
+
+  This change aligns the runner images with the official runner-images software and image
+  support policy, which keeps the **3 latest Go minor versions** preinstalled. Following
+  the removal, only Go 1.24.*, 1.25.*, and 1.26.* are preinstalled in the tool-cache.
+
+  Workflows that use `actions/setup-go` with `go-version: '1.22'` or `go-version: '1.23'`
+  will still work — `setup-go` automatically downloads the requested version at runtime
+  when it is no longer available in the tool-cache. However, this adds **30–90 seconds**
+  per run, since the binary must be fetched from Google's Go download servers rather than
+  read from the local disk.
+
+  Workflows that do NOT use `actions/setup-go` and assume Go 1.22/1.23 is on PATH by
+  default (e.g., raw `go build` steps on non-setup jobs) will now encounter
+  "go: command not found" or similar failures if they relied on Go being preinstalled.
+
+  Source: actions/runner-images#14237 (opened June 15, 2026).
+fix: |
+  **Option 1 — Upgrade to Go 1.24+ (recommended)**
+
+  Update `go-version` in your `actions/setup-go` step to a version in the tool-cache.
+  Go 1.24.* and later remain preinstalled. This is also the best practice, as Go 1.22
+  and 1.23 are nearing or past their upstream end-of-life.
+
+  **Option 2 — Pin the version explicitly and accept the download**
+
+  Keep your existing `actions/setup-go` version pin — setup-go will download Go 1.22
+  or 1.23 automatically. No workflow change is required; the only impact is a slower
+  build (30–90 seconds of additional download time per run). This is acceptable for
+  legacy projects that cannot yet upgrade Go.
+
+  **Option 3 — Use `go-version-file: go.mod` (auto-detection)**
+
+  Let `actions/setup-go` read the required Go version from `go.mod`:
+
+  ```yaml
+  - uses: actions/setup-go@v5
+    with:
+      go-version-file: go.mod
+  ```
+
+  When the `go` directive in `go.mod` specifies a removed version, setup-go downloads it
+  automatically. Updating `go.mod` to 1.24+ will then benefit from tool-cache hits.
+fix_code:
+  - language: yaml
+    label: 'Upgrade go-version to remain in tool-cache (fastest builds)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-go@v5
+              with:
+                # BEFORE (slow after June 22, 2026 — 1.22/1.23 must be downloaded):
+                # go-version: '1.23'
+                #
+                # AFTER (cache hit, instant):
+                go-version: '1.24'
+                cache: true
+            - run: go build ./...
+  - language: yaml
+    label: 'Use go-version-file to auto-detect version from go.mod'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-go@v5
+              with:
+                go-version-file: 'go.mod'
+                cache: true
+            - run: go test ./...
+prevention:
+  - 'Track the runner-images software support policy: only the 3 latest Go minor versions
+    are preinstalled in the tool-cache. Versions older than that must be downloaded.'
+  - 'Always use `actions/setup-go` with an explicit `go-version` or `go-version-file`
+    to ensure reproducible builds — never rely on Go being in PATH by default.'
+  - 'Subscribe to `actions/runner-images` announcements to get advance notice of
+    tool-cache removals; issues are typically opened 1–2 weeks before the change date.'
+  - 'Run `go mod tidy` and keep your `go.mod` on a recent Go minor version to benefit
+    from tool-cache hits and avoid download latency.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14237'
+    label: 'runner-images#14237: Go versions <=1.23 will be removed from tool-cache (June 22, 2026)'
+  - url: 'https://github.com/actions/setup-go'
+    label: 'actions/setup-go — automatic download for versions not in tool-cache'
+  - url: 'https://github.com/actions/runner-images#software-and-image-support'
+    label: 'runner-images: Software and image support policy (3 latest minor versions)'
+  - url: 'https://endoflife.date/go'
+    label: 'Go release EOL schedule'