From f354f7a36d01e319d0397b6d201f7e57fffec640 Mon Sep 17 00:00:00 2001
From: ccoVeille <3875889+ccoVeille@users.noreply.github.com>
Date: Sun, 7 Dec 2025 16:38:43 +0100
Subject: [PATCH] Document how to use Go version file as a fallback for Go
 matrix builds

This strategy is useful for projects that want to specify a default Go version
for their CI builds, while still allowing overrides through the Go matrix
to target the latest Go versions.
---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index 263ebd1..b23a924 100644
--- a/README.md
+++ b/README.md
@@ -353,6 +353,7 @@ The `go-version` input supports the following syntax:
 | Wildcard (minor) | `1.*` | Latest available version in the major version |
 | Pre-release | `1.24.0-rc.1` | Beta/RC versions for testing upcoming releases |
 | Aliases | `stable`, `oldstable` | Latest stable or previous stable release |
+| Empty string | `''` | No version specified; relies on `go-version-file` when provided |
 
 For more information about semantic versioning, see the [semver documentation](https://semver.org/).
 
@@ -383,6 +384,26 @@ For more information about semantic versioning, see the [semver documentation](h
     architecture: 'x64'
 ```
 
+### Matrix Testing with go-version-file fallback
+
+You can combine go-version with go-version-file in a matrix strategy to test across latest supported Go versions, and the minimal version specified in `go.mod` of your project.
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ['stable', 'oldstable', '']  # empty string to fall back on go-version-file
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: ${{ matrix.go-version }}
+          go-version-file: "go.mod" # this one is only used when go-version is not specified.
+      - run: go test ./...
+```
+
 ## Using setup-go on GHES
 
 setup-go comes pre-installed on GHES when Actions is enabled. For dynamic Go version downloads, the action fetches distributions from the [go-versions repository](https://github.com/actions/go-versions/) on github.com (external to your appliance).