> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/go

Common CircleCI tasks for the Go ( Golang ) programming language.


## Commands

### goreleaser-release

Build Go applications and release them on GitHub.
GoReleaser CLI must be installed and a GitHub Token
with write:packages permissions is also required.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `github-token` | string | GITHUB_TOKEN | A GitHub Token is with write:packages permissions is required.
 |
| `project-path` | string | $HOME | The path to the directory containing your Go project files:
.goreleaser.yaml, go.mod, main.go.
Defaults to $HOME.
 |
| `publish-release` | boolean | false | Set to true to publish release to GitHub
 |
| `validate-yaml` | boolean | false | Set to true to validate .goreleaser.yaml.
 |

### gotestsum

Runs 'go test ./...' but includes extensive parameterization for finer tuning


| Parameter | Type | Default | Description |
|---|---|---|---|
| `covermode` | string | atomic | mode used to count coverage |
| `coverprofile` | string | cover-source.out | file to save coverage profile |
| `junitfile` | string | unit-tests.xml | file to save junit format xml file |
| `packages` | string | ./... | import tests to run, by path glob. |
| `project-path` | string |  | The path to the directory containing your Go project files:
.goreleaser.yaml, go.mod, main.go.
Defaults to $HOME.
 |

### install

Install Go in a build. Supports Linux/amd64 and macOS/amd64.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache` | boolean | true | Whether or not to cache the binary. |
| `cache-key` | string | v2 | String to use in cache key. Typically overridden when needed to bust cache.
 |
| `version` | string | 1.16.5 | The Go version. |

### install-goreleaser

Install goreleaser


| Parameter | Type | Default | Description |
|---|---|---|---|
| `shell` | string | bash | The shell to use for running the script, windows should be bash but alpine may be sh.
 |
| `version` | string |  | The version of goreleaser to install. If not specified, the latest version will be installed.
 |

### load-build-cache

Load cached Go build cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |

### load-golangci-lint-cache

Load cached Go build cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |

### load-mod-cache

Load cached Go modules.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |

### mod-download

Run 'go mod download'.

### mod-download-cached

Download and cache Go modules

### save-build-cache

Save Go build cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |
| `path` | string | ~/.cache/go-build | Path to cache. |

### save-golangci-lint-cache

Save golangci-lint cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |
| `path` | string | ~/.cache/golangci-lint | Path to cache. |

### save-mod-cache

Save Go modules to cache.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |
| `path` | string | ~/go/pkg/mod | Path to cache. |

### test

Runs 'go test ./...' but includes extensive parameterization for finer tuning


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build_ldflags` | string |  | Arguments to pass on each go tool link invocation. |
| `build_tags` | string |  | A comma-separated list of additional build tags to consider satisfied during the build. |
| `count` | string | 1 | run each test and benchmark n times |
| `covermode` | enum | set | flag to set the coverage mode
(the go default is: "set", unless -race is enabled, in which case the go default is "atomic")
 |
| `coverpkg` | string | ./... | Apply coverage analysis in each test to packages matching the patterns.
(Sets -cover.)
 |
| `coverprofile` | string | cover-source.out | file to save coverage profile |
| `failfast` | boolean | false | do not start new tests after the first test failure |
| `no_output_timeout` | string | 10m | The amount of time to allow the command to run before timing out. |
| `packages` | string | ./... | Import tests to run, by path glob. |
| `parallel` | string | m | The number of programs, such as build commands or
test binaries, that can be run in parallel.
The default is GOMAXPROCS, normally the number of CPUs available.
 |
| `parallel-tests` | string | m | Allow parallel execution of test functions that call t.Parallel.
The value of this flag is the maximum number of tests to run
simultaneously.
By default, -parallel is set to the value of GOMAXPROCS.
 |
| `project-path` | string |  | The path to the directory containing your Go project files:
.goreleaser.yaml, go.mod, main.go.
Defaults to $HOME.
 |
| `race` | boolean | false | run tests with -race option
(if enabled, update covermode to be "atomic")
 |
| `run` | string |  | A regexp matching the names of the tests and examples that will be executed. |
| `short` | boolean | false | tell long-running tests to shorten their run time |
| `timeout` | string | 10m | timeout the test and panic after value - for situations where a test has a valid usecase to go longer than 10m |
| `verbose` | boolean | false | log all tests as they are run. Also print all text from Log and Logf calls even if the test succeeds. |

### with-cache

Runs the given steps


| Parameter | Type | Default | Description |
|---|---|---|---|
| `build` | boolean | true | Whether to use go-build cache. |
| `build-path` | string | ~/.cache/go-build | Location of go-build cache. |
| `checksum` | string | {{ checksum "go.sum" }} | Checksum template instruction |
| `golangci-lint` | boolean | false | Whether to use golangci-lint cache. Useful only in steps with linting, so defaults to false. |
| `golangci-lint-path` | string | ~/.cache/golangci-lint | Location of golangci-lint cache. |
| `key` | string |  | User-configurable component for cache key. Useful for avoiding collisions in complex workflows. |
| `mod` | boolean | false | Whether to use go module cache. If most of your dependencies are public, it is faster to use the public
Go module proxy, so this defaults to `false`.
 |
| `mod-path` | string | ~/go/pkg/mod | Location of go module cache. |
| `steps` | steps |  | The steps to run with caching. |

## Executors

### default

The official CircleCI Go Docker image on Docker Hub.
Found here: https://hub.docker.com/r/cimg/go


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string |  | The `cimg/go` Docker image version tag. |

## Examples

### goreleaser-release

Build Go applications and release them on GitHub.
Install GoReleaser CLI and add a GitHub Token with
write:packages permissions and store as environment variable.


```yaml
version: '2.1'
orbs:
  go: circleci/go@x.y
jobs:
  go-build-release:
    executor:
      name: go/default
      tag: 1.20.8
    steps:
      - go/install-goreleaser
      - go/goreleaser-release:
          project-path: /path/to/Go/project
          publish-release: true
          validate-yaml: true
workflows:
  main:
    jobs:
      - go-build-release
```

### test

Run go test ./... with additional (optional) parameters

```yaml
version: '2.1'
orbs:
  go: circleci/go@x.y
jobs:
  build:
    executor:
      name: go/default
      tag: '1.16'
    steps:
      - checkout
      - go/with-cache:
          steps:
            - go/mod-download
            - go/test:
                build_ldflags: '-X ''main.Version=v1.0.0'''
                build_tags: integration,e2e
                covermode: atomic
                failfast: true
                no_output_timeout: 15m
                race: true
                run: ^TestName$
                timeout: 15m
workflows:
  main:
    jobs:
      - build
```

### with-cache

Speeding up builds with the Go modules cache on CircleCI.

```yaml
version: '2.1'
orbs:
  go: circleci/go@x.y
jobs:
  build:
    executor:
      name: go/default
      tag: '1.23'
    steps:
      - checkout
      - go/with-cache:
          steps:
            - go/mod-download
            - go/test
workflows:
  main:
    jobs:
      - build
```