Cache keys now incorporate toolchain-specific metadata, eliminating version conflicts when switching between Go versions in your workflows.
**Migration Impact**
These changes ensure your workflows use the exact Go version your project requires, improving build reproducibility and reducing version-related issues.
For more details, see the [full release notes](https://github.com/actions/setup-go/releases).
### V5 Changes
- Upgraded Node.js runtime from node16 to node20
- Upgraded Node.js runtime from node16 to node20
- See [full release notes](https://github.com/actions/setup-go/releases) for complete details
- See [full release notes](https://github.com/actions/setup-go/releases)
## Version Resolution Behavior
The action follows this resolution order:
1. **Local cache** - Checks for a cached version match
2. **go-versions repository** - Pulls from the main branch of the [go-versions repository](https://github.com/actions/go-versions)
3. **Direct download** - Falls back to downloading directly from [go.dev](https://go.dev/dl/)
To change the default behavior, use the `check-latest` input.
> **Note**: The setup-go action uses executable binaries built by the Golang team. The action does not build Go from source code.
## Usage
## Usage Examples
See [action.yml](action.yml)
### Basic Usage
### Basic Setup
```yaml
```yaml
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '1.21'
go-version: '1.16.1' # The Go version to download (if necessary) and use
- run: go run hello.go
- run: go run hello.go
```
```
### Version Specifications
### Version Selection
#### Semantic Versioning
#### Semantic Versioning
```yaml
```yaml
# Using caret notation (latest patch release)
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '^1.21.1' # Latest patch release of 1.21.x
go-version: '^1.13.1' # The Go version to download (if necessary) and use
- run: go version
- run: go version
```
```
```yaml
```yaml
# Using comparison operators
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '>=1.20.0' # Version 1.20.0 or higher
go-version: '>=1.17.0'
- run: go version
- run: go version
```
```
> **Important**: Due to YAML parsing behavior, always wrap version numbers in single quotes:
> **Note**: Due to YAML parsing behavior, always wrap version numbers in single quotes:
> Without quotes, YAML interprets `1.20` as `1.2`, which may cause unexpected behavior.
#### Pre-release Versions
#### Pre-release Versions
```yaml
```yaml
# RC version
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '1.22.0-rc.1'
go-version: '1.18.0-rc.1' # The Go version to download (if necessary) and use
- run: go version
- run: go version
```
```
#### Version Aliases
**Stable Release**
```yaml
```yaml
# Beta version
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: 'stable' # Latest stable version
go-version: '1.16.0-beta.1' # The Go version to download (if necessary) and use
- run: go version
- run: go version
```
```
**Previous Stable Release**
### Check Latest Version
```yaml
steps:
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
with:
go-version: 'oldstable' # Previous stable version
- run: go version
```
> **Note**: Using aliases is equivalent to using the corresponding minor release with `check-latest: true`
The `check-latest` flag defaults to `false`. Use the default or set `check-latest` to `false` if you prefer stability and want to ensure a specific Go version is always used.
### Version from go.mod File
If `check-latest` is set to `true`, the action first checks if the cached version is the latest one. If the locally cached version is not the most up-to-date, a Go version will then be downloaded.
The action can automatically detect the Go version from your project's `go.mod` or `go.work` file:
> **Note**: Setting `check-latest` to `true` has performance implications as downloading Go versions is slower than using cached versions.
```yaml
```yaml
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version-file: 'go.mod'
go-version: '1.14'
- run: go version
check-latest: true
- run: go run hello.go
```
```
**Version Resolution from go.mod:**
### Using stable/oldstable Aliases
1. Uses the `toolchain` directive version if present
2. Falls back to the `go` directive version
3. If no patch version is specified, uses the latest available patch
> **Note**: If both `go-version` and `go-version-file` are provided, `go-version` takes precedence.
If `stable` is provided, action will get the latest stable version from the go-versions repository manifest.
### Check Latest Version
If `oldstable` is provided, when current release is 1.19.x, action will resolve version as 1.18.x, where x is the latest patch release.
> **Note**: Using these aliases will result in same version as using corresponding minor release with `check-latest` input set to `true`
```yaml
```yaml
# Latest stable version
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '1.21'
go-version: 'stable'
check-latest: true # Always check for the latest patch release
- `check-latest: true` - Downloads the latest version, slower but ensures up-to-date releases
### Caching
#### Automatic Caching
Caching is enabled by default and automatically handles:
- Go modules (based on `go.sum`)
- Build outputs
- Toolchain-specific metadata
```yaml
```yaml
# Previous stable version
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '1.21'
go-version: 'oldstable'
# cache: true (default)
- run: go run hello.go
- run: go run hello.go
```
```
#### Custom Cache Dependencies
### Caching Dependencies and Build Outputs
The action has built-in functionality for caching and restoring go modules and build outputs. It uses `toolkit/cache` under the hood but requires less configuration settings. The cache input is optional, and caching is turned on by default.
The action defaults to search for the dependency file - `go.sum` in the repository root, and uses its hash as a part of the cache key. Use `cache-dependency-path` input for cases when multiple dependency files are used, or they are located in different subdirectories. The input supports glob patterns.
If some problem that prevents success caching happens then the action issues the warning in the log and continues the execution of the pipeline.
For projects with multiple dependency files or monorepos:
#### Caching in Monorepos
```yaml
```yaml
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '1.21'
go-version: '1.17'
check-latest: true
cache-dependency-path: |
cache-dependency-path: |
subdir/go.sum
subdir/go.sum
tools/go.sum
tools/go.sum
# Alternative: cache-dependency-path: "**/*.sum"
- run: go run hello.go
- run: go run hello.go
```
```
**Using Glob Patterns:**
### Getting Go Version from go.mod File
```yaml
cache-dependency-path: "**/*.sum"
The `go-version-file` input accepts a path to a `go.mod` file or a `go.work` file that contains the version of Go to be used by a project. The version taken from this file will be:
```
1. The version from the `toolchain` directive, if there is one, otherwise
2. The version from the `go` directive
#### Disable Caching
The version can specify a patch version or omit it altogether (e.g., `go 1.22.0` or `go 1.22`).
- If a patch version is specified, that specific patch version will be used
- If no patch version is specified, it will search for the latest available patch version in the cache, versions-manifest.json, and the official Go language website, in that order
> **Note**: If both `go-version` and `go-version-file` inputs are provided then the `go-version` input is used.
The action will search for the `go.mod` file relative to the repository root:
```yaml
```yaml
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- uses: actions/setup-go@v6
with:
with:
go-version: '1.21'
go-version-file: 'path/to/go.mod'
cache: false
- run: go version
- run: go run hello.go
```
```
### Matrix Testing
### Matrix Testing
Test across multiple Go versions:
```yaml
```yaml
jobs:
jobs:
test:
build:
runs-on: ubuntu-latest
runs-on: ubuntu-latest
strategy:
strategy:
matrix:
matrix:
go-version: ['1.20', '1.21', '1.22']
go: [ '1.14', '1.13' ]
name: Go ${{ matrix.go }} sample
steps:
steps:
- uses: actions/checkout@v5
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
- name: Setup go
uses: actions/setup-go@v6
with:
with:
go-version: ${{ matrix.go-version }}
go-version: ${{ matrix.go }}
- run: go test ./...
- run: go run hello.go
```
```
## Advanced Configuration
## Version Resolution
### Supported Version Syntax
The action will first check the local cache for a version match. If a version is not found locally, it will pull it from the main branch of the [go-versions](https://github.com/actions/go-versions) repository. On miss or failure, it will fall back to downloading directly from [go dist](https://go.dev/dl/). To change the default behavior, please use the `check-latest` input.
| Syntax Type | Example | Description |
> **Note**: The setup-go action uses executable binaries which are built by Golang side. The action does not build golang from source code.
|-------------|---------|-------------|
| Specific version | `1.21.5` | Exact version |
| Semantic range | `^1.21.0` | Compatible with 1.21.0 |
| Comparison operators | `>=1.20.0` | Version 1.20.0 or higher |
- **SemVer's version range syntax**: `^1.13.1`, `>=1.18.0-rc.1`
with:
# Version or version range of Go to use
go-version: '1.21'
# Path to go.mod or go.work file
For more information about semantic versioning, please refer to [semver documentation](https://semver.org/).
go-version-file: 'go.mod'
# Check for latest version
## Using setup-go on GHES
check-latest: false
# GitHub token for authentication
`setup-go` comes pre-installed on the appliance with GHES if Actions is enabled. When dynamically downloading Go distributions, `setup-go` downloads distributions from `actions/go-versions` on github.com (outside of the appliance).
token: ${{ github.token }}
# Enable/disable caching
These calls to `actions/go-versions` are made via unauthenticated requests, which are limited to 60 requests per hour per IP. If more requests are made within the time frame, then the action leverages the raw API to retrieve the version-manifest. This approach does not impose a rate limit and hence facilitates unrestricted consumption. This is particularly beneficial for GHES runners, which often share the same IP, to avoid the quick exhaustion of the unauthenticated rate limit. If that fails as well the action will try to download versions directly from https://storage.googleapis.com/golang.
cache: true
# Path to dependency files for caching
If that fails as well you can get a higher rate limit with generating a personal access token on github.com and passing it as the token input to the action:
cache-dependency-path: 'go.sum'
# Architecture to install (auto-detected if not specified)
architecture: 'x64'
```
## Platform Support
### GitHub Enterprise Server (GHES)
When using setup-go on GHES:
1. **Pre-installed**: The action comes pre-installed if Actions is enabled
2. **Rate limits**: Unauthenticated requests are limited to 60/hour per IP
3. **Authentication**: Use a personal access token for higher rate limits:
```yaml
```yaml
- uses: actions/setup-go@v6
uses: actions/setup-go@v6
with:
with:
token: ${{ secrets.GH_DOTCOM_TOKEN }}
token: ${{ secrets.GH_DOTCOM_TOKEN }}
go-version: '1.21'
go-version: '1.18'
```
```
4. **Offline runners**: For runners without internet access, see [Setting up the tool cache on self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#using-self-hosted-runners-in-a-workflow)
If the runner is not able to access github.com, any Go versions requested during a workflow run must come from the runner's tool cache. See ["Setting up the tool cache on self-hosted runners without internet access"](https://docs.github.com/en/enterprise-server@latest/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access) for more information.
### Self-hosted Runners
For self-hosted runners without internet access, ensure Go versions are pre-cached in the runner's tool cache.
## Recommended Permissions
## 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:
```yaml
```yaml
permissions:
permissions:
contents: read # Required to checkout code and install dependencies
contents: read # access to check out code and install dependencies
```
```
## Troubleshooting
### Common Issues
**Version not found**
- Ensure the version exists in the [Go releases](https://go.dev/dl/)
- Check if you're using the correct version format
- Try using `check-latest: true`
**Caching issues**
- Cache conflicts may occur when switching Go versions
- V6 resolves this with toolchain-specific cache keys
- Manually clear cache if needed using GitHub Actions cache management
**YAML parsing**
- Always wrap version numbers in single quotes
- Avoid bare numbers that YAML might misinterpret
## License
## License
The scripts and documentation in this project are released under the [MIT License](LICENSE).
The scripts and documentation in this project are released under the [MIT License](LICENSE)
## Contributions
## Contributions
Contributions are welcome! See our [Contributor's Guide](docs/contributors.md) for details.
Contributions are welcome! See [Contributor's Guide](docs/contributors.md)
## Code of Conduct
## Code of Conduct
👋 Be nice. See our [Code of Conduct](CODE_OF_CONDUCT.md).
👋 Be nice. See our [code of conduct](CODE_OF_CONDUCT.md)
mahabaleshwars
3 months ago