- **Upgraded Node.js runtime from node20 to node24**
> Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release. See [Release Notes](https://github.com/actions/runner/releases/tag/v2.327.1)
- Supports both `go` and `toolchain` directives in `go.mod`. If the `toolchain` directive is present, its version is used; otherwise, the action falls back to the `go` directive.
The action resolves the requested version in the following order:
1.**Local cache** - Checks the local tool cache for a matching [semver](https://github.com/npm/node-semver#versions) version.
2.**go-versions repository** - If the requested version isn’t available in the tool cache, it pulls the version manifest from the `main` branch of the [go-versions repository](https://github.com/actions/go-versions/blob/main/versions-manifest.json).
3.**Direct download** - If that lookup misses or fails, it will fall back to downloading directly from the [official Go distribution site](https://go.dev/dl).
> **Note**: The `setup-go` action uses executable binaries built by the Go team and does not build Go binaries from source code.
## Supported version syntax
The `go-version` input supports the following syntax:
- Specific versions: `1.25`, `1.24.11`, `1.24.0-rc.1`, `1.23.0-beta.1`
- SemVer version range syntax: `^1.25.1`, `~1.24.1`, `>=1.25.0-rc.1`, `<1.25.0`, `>=1.22.0 <1.24.0`
- Aliases: `stable`, `oldstable`
- Wildcards: `1.25.x`, `1.x`
For details on Semantic Versioning, see [the semver package documentation](https://github.com/npm/node-semver).
> **Note**: Due to the peculiarities of YAML parsing, it is recommended to wrap the version in single quotation marks:
>
> ```yaml
> go-version: '1.20'
> ```
>
> The recommendation is based on the YAML parser's behavior, which interprets non-wrapped values as numbers and, in the case of version `1.20`, trims it down to `1.2`, which may not be very obvious.
For more usage examples, please refer to the section: [Using go-version input](docs/advanced-usage.md#using-the-go-version-input) of the [Advanced usage](docs/advanced-usage.md) guide.
## Recommended permissions
When using the `setup-go` action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:
The action includes built-in caching and restoration for Go modules and build outputs. It uses
[toolkit/cache](https://github.com/actions/toolkit/tree/main/packages/cache) under the hood, but requires less configuration.
The `cache` input is optional, and caching is enabled by default. To disable caching, set `cache: false`.
By default, the action looks for `go.mod` in the repository root and uses its hash as part of the cache key. Use the `cache-dependency-path` input when you have multiple dependency files, or when they’re located in different subdirectories. This input supports glob patterns.
Module sources (`GOMODCACHE`) and build outputs (`GOCACHE`) are cached separately. On the same runner OS, module sources can be reused across Go versions and runner architectures, while build outputs remain partitioned by Go version, runner architecture, and Linux runner image. The `cache-hit` output is `true` only when both cache entries are restored on their primary keys.
If caching cannot be performed for any reason, the action logs a warning and continues workflow execution.
For examples of using `cache-dependency-path`, see the [Caching](docs/advanced-usage.md#caching) section of the [Advanced usage](docs/advanced-usage.md) guide.
## Advanced usage
- [Using the go-version input](docs/advanced-usage.md#using-the-go-version-input)
- [Using the go-version-file input](docs/advanced-usage.md#using-the-go-version-file-input)
