<!--- Please direct any generic questions related to actions to our support community forum at https://github.community/c/code-to-cloud/github-actions/41 --->
<!--- Before opening up a new bug report, please make sure to check for similar existing issues -->
**Description:**
A clear and concise description of what the bug is.
**Action version:**
Specify the action version
**Platform:**
- [ ] Ubuntu
- [ ] macOS
- [ ] Windows
**Runner type:**
- [ ] Hosted
- [ ] Self-hosted
**Tools version:**
<!--- Please specify go version -->
**Repro steps:**
A description with steps to reproduce the issue. If your have a public example or repo to share, please provide the link.
<!--- Please direct any generic questions related to actions to our support community forum at https://github.community/c/code-to-cloud/github-actions/41 --->
<!--- Before opening up a new feature request, please make sure to check for similar existing issues and pull requests -->
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
This action sets up a go environment for use in 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.
# V3
The V3 edition of the action offers:
- Adds `GOBIN` to the `PATH`
- Proxy support
- Check latest version
- Bug fixes (including issues around version matching and semver)
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).
# V2
**Note:** The `setup-go` action uses executable binaries which are built by Golang side. The action does not build golang from source code.
The V2 offers:
- Adds GOBIN to the PATH
- Proxy Support
- stable input
- Bug Fixes (including issues around version matching and semver)
Matching by [semver spec](https://github.com/npm/node-semver):
Matching by semver spec:
```yaml
steps:
- uses: actions/checkout@v2
- uses: actions/setup-go@v2
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '^1.13.1' # The Go version to download (if necessary) and use.
- run: go version
- run: go version
```
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '>=1.17.0'
- run: go version
```
Matching an unstable pre-release:
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
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@v2
- uses: actions/setup-go@v2
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
stable: 'false'
go-version: '1.14.0-rc1' # The Go version to download (if necessary) and use.
- run: go version
go-version: '1.16.0-beta.1' # The Go version to download (if necessary) and use.
- run: go version
```
# Usage
See [action.yml](action.yml)
Basic:
## Basic
```yaml
steps:
- uses: actions/checkout@master
- uses: actions/setup-go@v1
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '1.9.3' # The Go version to download (if necessary) and use.
- run: go run hello.go
go-version: '1.16.1' # The Go version to download (if necessary) and use.
- run: go run hello.go
```
Matrix Testing:
## Check latest version
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.
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.
> Setting `check-latest` to `true` has performance implications as downloading Go versions is slower than using cached versions.
```yaml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '1.14'
check-latest: true
- run: go run hello.go
```
## Matrix testing
```yaml
jobs:
build:
runs-on: ubuntu-16.04
runs-on: ubuntu-latest
strategy:
matrix:
go: [ '1.13', '1.12' ]
go: [ '1.14', '1.13' ]
name: Go ${{ matrix.go }} sample
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v3
- name: Setup go
uses: actions/setup-go@v1
uses: actions/setup-go@v3
with:
go-version: ${{ matrix.go }}
- run: go run hello.go
```
### Supported version syntax
The `go-version` input supports the following 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`
For more information about semantic versioning, please refer to [semver](https://github.com/npm/node-semver) documentation.
# License
The scripts and documentation in this project are released under the [MIT License](LICENSE)
`actions/setup-go` is the one of the most popular action related to Golang in GitHub Actions. Many customers use it in conjunction with [actions/cache](https://github.com/actions/cache) to speed up dependency installation process.
See more examples on proper usage in [actions/cache documentation](https://github.com/actions/cache/blob/main/examples.md#go---modules).
# Goals & Anti-Goals
Integration of caching functionality into `actions/setup-go` action will bring the following benefits for action users:
- Decrease the entry threshold for using the cache for Go dependencies and simplify initial configuration
- Simplify YAML pipelines because there will be no need for additional steps to enable caching
- More users will use cache for Go so more customers will have fast builds!
We don't pursue the goal to provide wide customization of caching in scope of `actions/setup-go` action. The purpose of this integration is covering ~90% of basic use-cases. If user needs flexible customization, we should advice them to use `actions/cache` directly.
# Decision
- Add `cache` input parameter to `actions/setup-go`. For now, input will accept the following values:
- `true` - enable caching for go dependencies
- `false`- disable caching for go dependencies. This value will be set as default value
- Cache feature will be disabled by default to make sure that we don't break existing customers. We will consider enabling cache by default in next major releases
- Action will try to search a go.sum files in the repository and throw error in the scenario that it was not found
- The hash of found file will be used as cache key (the same approach like [actions/cache](https://github.com/actions/cache/blob/main/examples.md#go---modules) recommends)
- The following key cache will be used `${{ runner.os }}-go${{ go-version }}-${{ hashFiles('<go.sum-path>') }}`
- Action will cache global cache from the `go env GOMODCACHE` and `go env GOCACHE` commands.
- Add a `cache-dependency-path` input parameter to `actions/setup-go`. The new input will accept an array or regex of dependency files. The field will accept a path (relative to the repository root) to dependency files. If the provided path contains wildcards, the action will search all matching files and calculate a common hash like the ${{ hashFiles('**/go.sum') }} YAML construction does.
# Example of real use-cases
- With cache
```yml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '18'
cache: true
```
- With cache-dependency-path
```yml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '18'
cache: true
cache-dependency-path: **/go.sum
```
```yml
steps:
- uses: actions/checkout@v3
- uses: actions/setup-go@v3
with:
go-version: '18'
cache: true
cache-dependency-path: |
**/go.sum
**/go.mod
```
# Release process
As soon as functionality is implemented, we will release minor update of action. No need to bump major version since there are no breaking changes for existing users.
After that, we will update [starter-workflows](https://github.com/actions/starter-workflows/blob/main/ci/go.yml)
jojo43
3 years ago