This action sets up a go environment for use in actions by:
This action sets up a Go environment for use in GitHub Actions by:
- Optionally downloading and caching a version of Go by version and adding to `PATH`.
- Registering problem matchers for error output.
- ✅ Optionally downloading and caching a version of Go by version and adding to PATH
- ✅ Registering problem matchers for error output
# Breaking changes in V6
## 🚨 Breaking Changes in V6
## Node Runtime Upgrade
### Critical Requirements
Upgraded from Node 20 to Node 24
⚠️ Action Required: Ensure your runner is on version v2.327.1 or later for compatibility. [See Release Notes](https://github.com/actions/runner/releases/tag/v2.327.1)
#### Node Runtime Upgrade
- **Upgraded**: Node 20 → Node 24
- **⚠️ Action Required**: Ensure your runner is on version **v2.327.1 or later** for compatibility
- Cache keys now incorporate toolchain-specific metadata
- Eliminates version conflicts when switching between Go versions
- Improved workflow reliability
These changes ensure your workflows use the exact Go version your project requires, improving build reproducibility and reducing version-related issues.
### Migration Benefits
✅ Exact Go version matching
✅ Improved build reproducibility
✅ Reduced version-related issues
For more details, see the full release notes on the [releases page](https://github.com/actions/setup-go/releases/tag/v6.0.0)
For more details, see the [full release notes](https://github.com/actions/setup-go/releases).
# V5
---
The V5 edition of the action offers:
## 📋 Previous Versions
### V5 Changes
- Upgraded Node.js runtime from node16 to node20
- See [full V5 release notes](https://github.com/actions/setup-go/releases)
See full release notes on the [releases page](https://github.com/actions/setup-go/releases).
---
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/blob/main/versions-manifest.json)
repository. On miss or failure, it will fall back to downloading directly
from [go dist](https://storage.googleapis.com/golang). To change the default behavior, please use
the [check-latest input](#check-latest-version).
## 🚀 Usage
**Note:** The `setup-go` action uses executable binaries which are built by Golang side. The action does not build
golang from source code.
See [action.yml](action.yml)
Matching by [semver spec](https://github.com/npm/node-semver):
### Basic Setup
```yaml
steps:
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
with:
go-version: '^1.13.1' # The Go version to download (if necessary) and use.
- run: go version
go-version: '1.16.1' # The Go version to download (if necessary) and use.
- run: go run hello.go
```
### Version Selection Examples
#### Using Semantic Versioning
```yaml
# Caret notation (minor updates)
steps:
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
with:
go-version: '>=1.17.0'
go-version: '^1.13.1'
- run: go version
```
> **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.
Matching an unstable pre-release:
```yaml
# Comparison operators
steps:
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
with:
go-version: '1.18.0-rc.1' # The Go version to download (if necessary) and use.
go-version: '>=1.17.0'
- run: go version
```
> **⚠️ Important**: Always wrap version numbers in single quotes to prevent YAML parsing issues:
- Specific versions: `1.15`, `1.16.1`, `1.17.0-rc.2`, `1.16.0-beta.1`
- SemVer's version range syntax: `^1.13.1`, `>=1.18.0-rc.1`
For more information about semantic versioning, please refer to [semver documentation](https://github.com/npm/node-semver).
For more information about semantic versioning, please refer to [semver](https://github.com/npm/node-semver)
documentation.
---
## Using `setup-go` on GHES
## 🏢 Using setup-go on GHES
`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`](https://github.com/actions/go-versions) on github.com (outside of the appliance).
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).
These calls to `actions/go-versions` are made via unauthenticated requests, which are limited to [60 requests per hour per IP](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting).
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.
These calls to `actions/go-versions` are made via unauthenticated requests (limited to 60 requests per hour per IP). If more requests are needed:
If that fails as well you can get a higher rate limit with [generating a personal access token on github.com](https://github.com/settings/tokens/new) and passing it as the `token` input to the action:
1. The action leverages the raw API to retrieve the version-manifest (no rate limit)
2. If that fails, attempts to download directly from `https://storage.googleapis.com/golang`
### Using a Personal Access Token
For higher rate limits:
```yaml
uses: actions/setup-go@v6
@ -278,27 +262,41 @@ with:
go-version: '1.18'
```
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@3.2/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access)"
for more information.
If the runner cannot 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@3.2/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access) for more information.
---
## 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:
When using the setup-go action in your GitHub Actions workflow, set the following permissions:
```yaml
permissions:
contents: read # access to check out code and install dependencies
```
# License
---
## ⚙️ How It Works
### Version Resolution Order
1. **Local cache** check for version match
2. **go-versions repository** (main branch) on cache miss
3. **Direct download** from go dist as fallback
> **Note**: The setup-go action uses executable binaries built by the Golang team. The action does not build Go from source code.
---
## 📄 License
The scripts and documentation in this project are released under the [MIT License](LICENSE)
# Contributions
## 🤝 Contributions
Contributions are welcome! See [Contributor's Guide](docs/contributors.md)
## Code of Conduct
## 👮 Code of Conduct
:wave: Be nice. See [our code of conduct](CODE_OF_CONDUCT.md)
👋 Be nice. See our [code of conduct](CODE_OF_CONDUCT.md)
mahabaleshwars
6 months ago