diff --git a/README.md b/README.md index a947b91..6d6f0ee 100644 --- a/README.md +++ b/README.md @@ -3,116 +3,68 @@ [![Basic validation](https://github.com/actions/setup-go/actions/workflows/basic-validation.yml/badge.svg)](https://github.com/actions/setup-go/actions/workflows/basic-validation.yml) [![Validate 'setup-go'](https://github.com/actions/setup-go/actions/workflows/versions.yml/badge.svg)](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: @@ -196,31 +185,15 @@ steps: go-version: '1.17' check-latest: true cache-dependency-path: | - subdir/go.sum - tools/go.sum - # cache-dependency-path: "**/*.sum" - + subdir/go.sum + tools/go.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 + 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) \ No newline at end of file