mirror of https://github.com/actions/setup-go.git
Readme file update
This commit is contained in:
mahabaleshwars
parent
fef3dee3c5
commit
871ad8f94d
306
README.md
306
README.md
|
|
@ -3,116 +3,68 @@
|
|||
[](https://github.com/actions/setup-go/actions/workflows/basic-validation.yml)
|
||||
[](https://github.com/actions/setup-go/actions/workflows/versions.yml)
|
||||
|
||||
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
|
||||
- **Reference**: [Release Notes](https://github.com/actions/setup-go/releases)
|
||||
|
||||
## Enhanced Go Toolchain Management
|
||||
### Enhanced Go Toolchain Management
|
||||
|
||||
V6 introduces significant improvements to ensure reliable and consistent Go version selection:
|
||||
|
||||
### Toolchain Directive Support
|
||||
#### 1. Toolchain Directive Support
|
||||
Now correctly interprets both `go` and `toolchain` directives from `go.mod`:
|
||||
|
||||
Now correctly interprets both go and toolchain directives from go.mod:
|
||||
```
|
||||
```go
|
||||
go 1.21.0 // Minimum required version
|
||||
toolchain go1.21.6 // V6 uses this exact version
|
||||
```
|
||||
### Advanced Version Resolution
|
||||
|
||||
#### 2. Advanced Version Resolution
|
||||
Supports comprehensive version patterns:
|
||||
|
||||
Comparison operators: >=1.21.0, <1.22.0
|
||||
Semantic versioning: ~1.21.0 (patch updates), ^1.21.0 (minor updates)
|
||||
Wildcards: 1.21.x, 1.*
|
||||
| Pattern Type | Examples | Description |
|
||||
|-------------|----------|-------------|
|
||||
| **Comparison Operators** | `>=1.21.0`, `<1.22.0` | Range-based selection |
|
||||
| **Semantic Versioning** | `~1.21.0`, `^1.21.0` | Patch/minor updates |
|
||||
| **Wildcards** | `1.21.x`, `1.*` | Flexible matching |
|
||||
|
||||
### Intelligent Caching
|
||||
#### 3. Intelligent Caching
|
||||
- Cache keys now incorporate toolchain-specific metadata
|
||||
- Eliminates version conflicts when switching between Go versions
|
||||
- Improved workflow reliability
|
||||
|
||||
Cache keys now incorporate toolchain-specific metadata, eliminating version conflicts when switching between Go versions in your workflows.
|
||||
### Migration Benefits
|
||||
✅ Exact Go version matching
|
||||
✅ Improved build reproducibility
|
||||
✅ Reduced version-related issues
|
||||
|
||||
### Migration Impact
|
||||
For more details, see the [full release notes](https://github.com/actions/setup-go/releases).
|
||||
|
||||
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 on the [releases page](https://github.com/actions/setup-go/releases/tag/v6.0.0)
|
||||
|
||||
# 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).
|
||||
|
||||
**Note:** The `setup-go` action uses executable binaries which are built by Golang side. The action does not build
|
||||
golang from source code.
|
||||
|
||||
Matching by [semver spec](https://github.com/npm/node-semver):
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '>=1.17.0'
|
||||
- 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
|
||||
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.
|
||||
- run: go version
|
||||
```
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '1.16.0-beta.1' # The Go version to download (if necessary) and use.
|
||||
- run: go version
|
||||
```
|
||||
|
||||
# Usage
|
||||
## 🚀 Usage
|
||||
|
||||
See [action.yml](action.yml)
|
||||
|
||||
## Basic
|
||||
### Basic Setup
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -123,17 +75,65 @@ steps:
|
|||
- run: go run hello.go
|
||||
```
|
||||
|
||||
## Check latest version
|
||||
### Version Selection Examples
|
||||
|
||||
The `check-latest` flag defaults to `false`. Use the default or set `check-latest` to `false` if you prefer stability
|
||||
and if you want to ensure a specific Go version is always used.
|
||||
#### Using Semantic Versioning
|
||||
|
||||
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. Set `check-latest` to `true` if you
|
||||
want the most up-to-date Go version to always be used.
|
||||
```yaml
|
||||
# Caret notation (minor updates)
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '^1.13.1'
|
||||
- run: go version
|
||||
```
|
||||
|
||||
> Setting `check-latest` to `true` has performance implications as downloading Go versions is slower than using cached
|
||||
> versions.
|
||||
```yaml
|
||||
# Comparison operators
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '>=1.17.0'
|
||||
- run: go version
|
||||
```
|
||||
|
||||
> **⚠️ Important**: Always wrap version numbers in single quotes to prevent YAML parsing issues:
|
||||
> ```yaml
|
||||
> go-version: '1.20' # ✅ Correct
|
||||
> go-version: 1.20 # ❌ Incorrect - YAML interprets as 1.2
|
||||
> ```
|
||||
|
||||
#### Pre-release Versions
|
||||
|
||||
```yaml
|
||||
# RC version
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '1.18.0-rc.1'
|
||||
- run: go version
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Beta version
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
with:
|
||||
go-version: '1.16.0-beta.1'
|
||||
- run: go version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Advanced Features
|
||||
|
||||
### Check Latest Version
|
||||
|
||||
The `check-latest` flag defaults to `false` for stability. Set to `true` if you want the most up-to-date Go version.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -145,18 +145,12 @@ steps:
|
|||
- run: go run hello.go
|
||||
```
|
||||
|
||||
## Using stable/oldstable aliases
|
||||
> **Note**: Setting `check-latest: true` has performance implications as downloading Go versions is slower than using cached versions.
|
||||
|
||||
If `stable` is provided, action will get the latest stable version from
|
||||
the [`go-versions`](https://github.com/actions/go-versions/blob/main/versions-manifest.json) repository manifest.
|
||||
|
||||
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`
|
||||
### Using Stable/Oldstable Aliases
|
||||
|
||||
```yaml
|
||||
# Latest stable version
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
|
|
@ -166,6 +160,7 @@ steps:
|
|||
```
|
||||
|
||||
```yaml
|
||||
# Previous stable version
|
||||
steps:
|
||||
- uses: actions/checkout@v5
|
||||
- uses: actions/setup-go@v6
|
||||
|
|
@ -174,19 +169,13 @@ steps:
|
|||
- run: go run hello.go
|
||||
```
|
||||
|
||||
## Caching dependency files and build outputs:
|
||||
> **Note**: Using these aliases will result in the same version as using the corresponding minor release with `check-latest: true`
|
||||
|
||||
The action has a built-in functionality for caching and restoring 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 settings.
|
||||
The `cache` input is optional, and caching is turned on by default.
|
||||
### Caching Dependencies and Build Outputs
|
||||
|
||||
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.
|
||||
The action has built-in functionality for caching and restoring go modules and build outputs. Caching is **enabled by default**.
|
||||
|
||||
If some problem that prevents success caching happens then the action issues the warning in the log and continues the execution of the pipeline.
|
||||
|
||||
**Caching in monorepos**
|
||||
#### Caching in Monorepos
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -198,29 +187,13 @@ steps:
|
|||
cache-dependency-path: |
|
||||
subdir/go.sum
|
||||
tools/go.sum
|
||||
# cache-dependency-path: "**/*.sum"
|
||||
|
||||
# Alternative: cache-dependency-path: "**/*.sum"
|
||||
- run: go run hello.go
|
||||
```
|
||||
```
|
||||
|
||||
## Getting go version from the go.mod file
|
||||
### Getting Go Version from go.mod
|
||||
|
||||
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 thils file will be:
|
||||
|
||||
- The version from the `toolchain` directive, if there is one, otherwise
|
||||
- The version from the `go` directive
|
||||
|
||||
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](https://github.com/actions/go-versions/blob/main/versions-manifest.json), and the
|
||||
[official Go language website](https://golang.org/dl/?mode=json&include=all), in that order.
|
||||
|
||||
If both the `go-version` and the `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
|
||||
The action can read the Go version directly from your `go.mod` or `go.work` file:
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
|
|
@ -231,7 +204,13 @@ steps:
|
|||
- run: go version
|
||||
```
|
||||
|
||||
## Matrix testing
|
||||
Priority order for version selection:
|
||||
1. `toolchain` directive (if present)
|
||||
2. `go` directive
|
||||
|
||||
> **Note**: If both `go-version` and `go-version-file` are provided, `go-version` takes precedence.
|
||||
|
||||
### Matrix Testing
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
|
|
@ -250,26 +229,31 @@ jobs:
|
|||
- run: go run hello.go
|
||||
```
|
||||
|
||||
### Supported version syntax
|
||||
---
|
||||
|
||||
The `go-version` input supports the following syntax:
|
||||
## 📝 Supported Version Syntax
|
||||
|
||||
- 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`
|
||||
The `go-version` input supports:
|
||||
|
||||
For more information about semantic versioning, please refer to [semver](https://github.com/npm/node-semver)
|
||||
documentation.
|
||||
- **Specific versions**: `1.15`, `1.16.1`, `1.17.0-rc.2`, `1.16.0-beta.1`
|
||||
- **SemVer ranges**: `^1.13.1`, `>=1.18.0-rc.1`
|
||||
|
||||
## Using `setup-go` on GHES
|
||||
For more information about semantic versioning, please refer to [semver documentation](https://github.com/npm/node-semver).
|
||||
|
||||
`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).
|
||||
---
|
||||
|
||||
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.
|
||||
## 🏢 Using setup-go on GHES
|
||||
|
||||
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:
|
||||
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 (limited to 60 requests per hour per IP). If more requests are needed:
|
||||
|
||||
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
|
||||
---
|
||||
|
||||
When using the `setup-go` action in your GitHub Actions workflow, it is recommended to set the following permissions to ensure proper functionality:
|
||||
## 🔒 Recommended Permissions
|
||||
|
||||
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)
|
||||
Loading…
Reference in New Issue