2019-07-17 14:50:58 +00:00
# setup-go
2019-06-19 13:44:17 +00:00
2022-12-23 03:03:14 +00:00
[![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)
2022-03-31 19:29:52 +00:00
[![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)
2019-08-12 19:13:31 +00:00
2019-07-17 14:50:58 +00:00
This action sets up a go environment for use in actions by:
2019-06-19 13:44:17 +00:00
2022-03-31 19:29:52 +00:00
- Optionally downloading and caching a version of Go by version and adding to `PATH` .
- Registering problem matchers for error output.
2019-07-17 14:50:58 +00:00
2024-04-15 14:19:11 +00:00
# V5
The V5 edition of the action offers:
- Upgraded Node.js runtime from node16 to node20
See full release notes on the [releases page ](https://github.com/actions/setup-go/releases ).
2023-03-10 15:25:35 +00:00
# V4
The V4 edition of the action offers:
- Enabled caching by default
The action will try to enable caching unless the `cache` input is explicitly set to false.
Please see "[Caching dependency files and build outputs](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs)" for more information.
2022-03-25 08:53:28 +00:00
# V3
2020-02-09 19:39:34 +00:00
2022-03-31 19:29:52 +00:00
The V3 edition of the action offers:
- Adds `GOBIN` to the `PATH`
- Proxy support
2022-02-09 11:59:04 +00:00
- Check latest version
2022-05-25 10:07:29 +00:00
- Caching packages dependencies
2022-12-12 09:58:49 +00:00
- stable and oldstable aliases
2022-05-25 10:07:29 +00:00
- Bug Fixes (including issues around version matching and semver)
2020-02-09 19:39:34 +00:00
2023-03-10 15:25:35 +00:00
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 ).
2020-07-20 16:50:40 +00:00
2023-03-10 15:25:35 +00:00
**Note:** The `setup-go` action uses executable binaries which are built by Golang side. The action does not build
golang from source code.
2022-04-20 14:11:14 +00:00
2021-12-01 11:10:32 +00:00
Matching by [semver spec ](https://github.com/npm/node-semver ):
2022-03-31 19:29:52 +00:00
2020-02-09 19:39:34 +00:00
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2021-11-08 10:28:08 +00:00
with:
go-version: '^1.13.1' # The Go version to download (if necessary) and use.
- run: go version
2020-02-09 19:39:34 +00:00
```
2022-03-29 19:16:03 +00:00
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2022-03-29 19:16:03 +00:00
with:
go-version: '>=1.17.0'
- run: go version
```
2023-06-08 13:37:31 +00:00
> **Note**: Due to the peculiarities of YAML parsing, it is recommended to wrap the version in single quotation marks:
2023-09-05 15:42:39 +00:00
>
2023-06-08 13:37:31 +00:00
> ```yaml
> go-version: '1.20'
2024-04-18 13:33:57 +00:00
> ```
2023-09-05 15:42:39 +00:00
>
2023-06-08 13:37:31 +00:00
> 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.
2024-04-18 13:33:57 +00:00
2020-02-11 00:18:01 +00:00
Matching an unstable pre-release:
2022-04-01 13:27:16 +00:00
2020-02-11 00:18:01 +00:00
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2022-03-29 19:16:03 +00:00
with:
go-version: '1.18.0-rc.1' # The Go version to download (if necessary) and use.
- run: go version
```
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2021-11-08 10:28:08 +00:00
with:
2022-03-29 19:16:03 +00:00
go-version: '1.16.0-beta.1' # The Go version to download (if necessary) and use.
2021-11-08 10:28:08 +00:00
- run: go version
2020-02-11 00:18:01 +00:00
```
2019-07-17 14:50:58 +00:00
# Usage
See [action.yml ](action.yml )
2022-04-01 13:27:16 +00:00
## Basic
2022-03-31 19:29:52 +00:00
2019-07-17 14:50:58 +00:00
```yaml
2019-07-26 01:28:46 +00:00
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2022-02-09 11:59:04 +00:00
with:
go-version: '1.16.1' # The Go version to download (if necessary) and use.
- run: go run hello.go
```
2022-04-01 13:27:16 +00:00
## Check latest version
2022-02-09 11:59:04 +00:00
2023-03-10 15:25:35 +00:00
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.
2022-02-09 11:59:04 +00:00
2023-03-10 15:25:35 +00:00
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.
2022-02-09 11:59:04 +00:00
2023-03-10 15:25:35 +00:00
> Setting `check-latest` to `true` has performance implications as downloading Go versions is slower than using cached
> versions.
2022-02-09 11:59:04 +00:00
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2021-11-08 10:28:08 +00:00
with:
2022-02-09 11:59:04 +00:00
go-version: '1.14'
check-latest: true
2021-11-08 10:28:08 +00:00
- run: go run hello.go
2019-07-17 14:50:58 +00:00
```
2022-12-12 09:58:49 +00:00
## Using stable/oldstable aliases
2023-03-10 15:25:35 +00:00
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.
2022-12-12 09:58:49 +00:00
2023-03-10 15:25:35 +00:00
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.
2022-12-12 09:58:49 +00:00
2023-03-10 15:25:35 +00:00
**Note:** using these aliases will result in same version as using corresponding minor release with `check-latest` input
set to `true`
2022-12-12 09:58:49 +00:00
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2022-12-12 09:58:49 +00:00
with:
go-version: 'stable'
- run: go run hello.go
```
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2022-12-12 09:58:49 +00:00
with:
go-version: 'oldstable'
- run: go run hello.go
```
2022-05-25 10:07:29 +00:00
## Caching dependency files and build outputs:
2023-03-10 15:25:35 +00:00
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.
2022-05-25 10:07:29 +00:00
2023-03-10 15:25:35 +00:00
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
2023-08-29 13:43:02 +00:00
in different subdirectories. The input supports glob patterns.
2022-05-25 10:07:29 +00:00
2023-09-05 15:42:39 +00:00
If some problem that prevents success caching happens then the action issues the warning in the log and continues the execution of the pipeline.
2022-05-25 10:07:29 +00:00
**Caching in monorepos**
2023-03-10 15:25:35 +00:00
2022-05-25 10:07:29 +00:00
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2022-05-25 10:07:29 +00:00
with:
go-version: '1.17'
check-latest: true
2023-08-25 10:31:19 +00:00
cache-dependency-path: |
2023-09-05 15:42:39 +00:00
subdir/go.sum
tools/go.sum
2023-08-25 10:31:19 +00:00
# cache-dependency-path: "**/*.sum"
2022-05-25 10:07:29 +00:00
- run: go run hello.go
```
2023-03-10 15:25:35 +00:00
2022-05-12 08:04:39 +00:00
## Getting go version from the go.mod file
2024-04-18 13:33:57 +00:00
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 `go` directive in `go.mod` 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
2024-04-18 14:57:07 +00:00
[official Go language website ](https://go.dev/dl/?mode=json&include=all ), in that order.
2022-05-12 08:04:39 +00:00
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
```yaml
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2024-01-29 16:18:45 +00:00
- uses: actions/setup-go@v5
2023-03-10 15:25:35 +00:00
with:
go-version-file: 'path/to/go.mod'
- run: go version
2022-05-12 08:04:39 +00:00
```
2019-07-17 14:50:58 +00:00
2022-04-01 13:27:16 +00:00
## Matrix testing
2022-03-31 19:29:52 +00:00
2019-07-17 14:50:58 +00:00
```yaml
jobs:
build:
2022-01-12 06:40:09 +00:00
runs-on: ubuntu-latest
2019-07-17 14:50:58 +00:00
strategy:
matrix:
2020-07-22 11:52:29 +00:00
go: [ '1.14', '1.13' ]
2019-07-17 14:50:58 +00:00
name: Go ${{ matrix.go }} sample
2019-07-26 01:28:46 +00:00
steps:
2023-09-05 15:42:39 +00:00
- uses: actions/checkout@v4
2019-07-17 14:50:58 +00:00
- name: Setup go
2024-01-29 16:18:45 +00:00
uses: actions/setup-go@v5
2019-07-17 14:50:58 +00:00
with:
2019-08-13 20:31:11 +00:00
go-version: ${{ matrix.go }}
2019-07-17 14:50:58 +00:00
- run: go run hello.go
```
2019-06-19 13:44:17 +00:00
2021-12-01 11:10:32 +00:00
### Supported version syntax
2022-03-31 19:29:52 +00:00
2021-12-01 11:10:32 +00:00
The `go-version` input supports the following syntax:
2022-04-01 13:27:16 +00:00
- 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`
2023-03-10 15:25:35 +00:00
For more information about semantic versioning, please refer to [semver ](https://github.com/npm/node-semver )
documentation.
2021-12-01 11:10:32 +00:00
2022-11-02 11:21:18 +00:00
## Using `setup-go` on GHES
2023-03-10 15:25:35 +00:00
`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 you will start to see rate-limit errors during downloading that looks
like: `##[error]API rate limit exceeded for...` . After that error the action will try to download versions directly
from https://storage.googleapis.com/golang, but it also can have rate limit so it's better to put token.
2022-11-02 11:21:18 +00:00
2023-03-10 15:25:35 +00:00
To get a higher rate limit, you
can [generate a personal access token on github.com ](https://github.com/settings/tokens/new ) and pass it as the `token`
input for the action:
2022-11-02 11:21:18 +00:00
```yaml
2024-01-29 16:18:45 +00:00
uses: actions/setup-go@v5
2022-11-02 11:21:18 +00:00
with:
token: ${{ secrets.GH_DOTCOM_TOKEN }}
2023-06-05 11:06:05 +00:00
go-version: '1.18'
2022-11-02 11:21:18 +00:00
```
2023-03-10 15:25:35 +00:00
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.
2022-11-02 11:21:18 +00:00
2019-06-19 13:44:17 +00:00
# License
The scripts and documentation in this project are released under the [MIT License ](LICENSE )
# Contributions
2022-04-01 13:27:16 +00:00
Contributions are welcome! See [Contributor's Guide ](docs/contributors.md )
2020-02-09 05:21:39 +00:00
## Code of Conduct
2022-09-05 10:39:44 +00:00
:wave: Be nice. See [our code of conduct ](CODE_OF_CONDUCT.md )