### Install Go Binary

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Installs a specific version of the Go binary. Supports caching for faster subsequent installations.

```yaml
go/install:
  version: "1.23.0"
  cache: true
```

--------------------------------

### Go Version Installation Parameters

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Configures the Go version to install, including options for caching the binary and customizing the cache key.

```yaml
install:
  version: "1.23.0"
  cache: true
  cache-key: "v2"
```

--------------------------------

### Install and Use golangci-lint

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Install golangci-lint and use it within a CircleCI job. Leverages the go/with-cache executor for caching the linter.

```yaml
- run:
    name: Install golangci-lint
    command: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
- go/with-cache:
    golangci-lint: true
    steps:
      - run: golangci-lint run ./...
```

--------------------------------

### Install gotestsum for Go Tests

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

If the 'gotestsum' command is not found, install it using 'go install' before using the 'go/gotestsum' orb. This ensures the tool is available in the executor environment.

```yaml
- run:
    name: Install gotestsum
    command: go install github.com/gotestyourself/gotestsum@latest
- go/gotestsum:
    packages: "./..."
```

--------------------------------

### Go Orb Install Command

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Install a specific version of Go using the `go/install` command. Supports caching of the Go binary for faster rebuilds. You can customize the cache key to bust the cache if needed.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    docker:
      - image: cimg/ubuntu:2024.04
    steps:
      - go/install:
          version: "1.23.0"
          cache: true
          cache-key: "v2"
      - run: go version
```

--------------------------------

### go/install Command

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Installs Go in a build environment, supporting various architectures and offering optional caching for the Go binary. It allows specifying the Go version and a custom cache key.

```APIDOC
## go/install Command

### Description
Install Go in a build. Supports Linux/amd64, Linux/arm64, macOS/amd64, and macOS/arm64. Includes optional caching of the Go binary.

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters:
* **version** (string, optional, default: `1.26.3`) - The Go version to install (e.g., `1.23`, `1.22.5`)
* **cache** (boolean, optional, default: `true`) - Whether to cache the Go binary for faster rebuilds
* **cache-key** (string, optional, default: `v2`) - String to use in cache key; override to bust cache when needed

### Steps:
1. Initializes OS detection via `os-detect` orb
2. If caching enabled: removes old Go installation and prepares cache directory
3. Restores cached Go binary if available
4. Downloads and installs Go binary from official sources (or builds from source on Alpine)
5. Verifies installation by running `go version`
6. If caching enabled: saves Go binary to cache

### Throws/Errors:
- Installation fails if download timeouts or network issues occur (script retries 3 times with 5-second delays)
- On Alpine Linux, fails if build tools (gcc, musl-dev) cannot be installed
- On non-Alpine, fails if Go binary cannot be downloaded from https://dl.google.com/go/

### Usage Example:
```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    docker:
      - image: cimg/ubuntu:2024.04
    steps:
      - go/install:
          version: "1.23.0"
          cache: true
          cache-key: "v2"
      - run: go version
```
```

--------------------------------

### Go Orb Test Command Usage Example

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

This example demonstrates how to use the 'go/test' command within a CircleCI configuration. It enables race detection, sets the covermode to atomic, enforces failfast behavior, filters tests to run, specifies a timeout, sets a no-output timeout, includes integration build tags, and passes build linker flags.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/test:
          race: true
          covermode: "atomic"
          failfast: true
          run: "^TestCore"
          timeout: "15m"
          no_output_timeout: "20m"
          build_tags: "integration"
          build_ldflags: "-X 'main.Version=1.0.0'"
```

--------------------------------

### Install Custom Go Version for Testing

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Installs a specific Go version before running tests in CircleCI.

```yaml
- go/install:
    version: "1.22.5"
- go/test
```

--------------------------------

### GoReleaser Installation Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Configure the installation of GoReleaser, specifying the version and shell. If the version is empty, the latest version will be fetched.

```yaml
go/install-goreleaser:
  version: "v1.24.0"
  shell: "bash"
```

--------------------------------

### Go Orb with-cache Usage Example

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Use this composite command to run steps with Go build, module, and golangci-lint caching enabled. Configure cache paths and checksum strategies as needed.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          golangci-lint: false
          key: "v1"
          steps:
            - go/mod-download
            - go/test
            - run:
                name: Run linter
                command: golangci-lint run
```

--------------------------------

### Install GoReleaser CLI

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Installs the GoReleaser CLI tool, supporting various OS and architectures. Specify a version or install the latest.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  release:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/install-goreleaser:
          version: "v1.24.0"
      - run: goreleaser --version
```

--------------------------------

### Install GoReleaser and Release

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Install a specific version of GoReleaser and then proceed with the release process. Set validate-yaml to true and publish-release to false for initial testing.

```yaml
- go/install-goreleaser:
    version: "v1.24.0"
- go/goreleaser-release:
    validate-yaml: true
    publish-release: false
```

--------------------------------

### Go Orb mod-download Usage Example

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Run 'go mod download' to fetch and cache Go module dependencies. This command is useful for ensuring all project dependencies are downloaded before subsequent build or test steps.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/mod-download
      - go/test
```

--------------------------------

### Install Alpine Build Tools for Go

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

When installing Go on Alpine Linux, pre-install build tools like bash, gcc, and musl-dev using 'apk add' before running 'go/install'.

```yaml
- run:
    name: Install Alpine build tools
    command: apk add --no-cache bash gcc musl-dev
- go/install:
    version: "1.23.0"
```

--------------------------------

### GoReleaser Release Configuration Example

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Example CircleCI configuration for a GoReleaser release job. This snippet demonstrates how to set up the `go/goreleaser-release` command with various parameters.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  release:
    executor:
      name: go/default
      tag: "1.23"
    environment:
      # Set GITHUB_TOKEN in CircleCI project settings
      GITHUB_TOKEN: $GITHUB_TOKEN
    steps:
      - checkout
      - go/install-goreleaser:
          version: "v1.24.0"
      - go/goreleaser-release:
          github-token: GITHUB_TOKEN
          project-path: "."
          validate-yaml: true
          publish-release: true

```

--------------------------------

### Increase Go Installation Timeout

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

If Go installation times out, increase the timeout by using the 'go/install' command with caching enabled. The install script retries automatically.

```yaml
- go/install:
    version: "1.23.0"
    cache: true  # Cache helps on retry
```

--------------------------------

### Check arm64 Dependency Support

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Verify that your project's dependencies support the arm64 architecture. Run `go get -u ./...` to update dependencies and `go build` to check for build errors.

```bash
go get -u ./... && go build -o /dev/null
```

--------------------------------

### Go Orb mod-download-cached Usage Example

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Use this composite command to download and cache Go modules in a single step, streamlining dependency management by combining load, download, and save cache operations.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/mod-download-cached
      - go/test
```

--------------------------------

### Multi-Platform Release with GoReleaser

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Install a specific version of GoReleaser and use it to publish a release. This is for projects that use GoReleaser for managing releases.

```yaml
- go/install-goreleaser:
    version: "v1.24.0"
- go/goreleaser-release:
    validate-yaml: true
    publish-release: true

```

--------------------------------

### Use Go Executor with Alpine Build Tools

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Alternatively, use a non-Alpine Go executor image that already includes build tools, such as '1.23-alpine', to avoid manual installation of build dependencies.

```yaml
executor:
  name: go/default
  tag: "1.23-alpine"  # Already has build tools
```

--------------------------------

### Go Orb load-mod-cache Usage Example

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Load cached Go modules using a specified key and checksum for cache validation. This is useful for restoring dependencies to speed up build times.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/load-mod-cache:
          key: "v1"
          checksum: '{{ checksum "go.sum" }}'
```

--------------------------------

### Integrate Go Orb with Other Orbs

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Combine the Go Orb with other CircleCI orbs, such as Codecov, for a comprehensive CI/CD pipeline. This example shows testing and uploading coverage reports.

```yaml
orbs:
  go: circleci/go@x.y
  codecov: codecov/codecov@x.y

jobs:
  test:
    executor: go/default
    steps:
      - checkout
      - go/test:
          coverprofile: coverage.out
      - codecov/upload:
          file: coverage.out
```

--------------------------------

### Run Go Tests with Gotestsum

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Executes Go tests using gotestsum, providing JUnit XML output and formatted results. Ensure gotestsum is installed in the executor before use.

```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - run:
          name: Install gotestsum
          command: |
            go install github.com/gotestyourself/gotestsum@latest
      - go/gotestsum:
          packages: "./..."
          junitfile: "test-results.xml"
          coverprofile: "coverage.out"
```

--------------------------------

### Run Basic Tests

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Execute the default Go tests for your project. This is the simplest way to run tests.

```yaml
- go/test

```

--------------------------------

### Go Orb Workflow with Caching

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Demonstrates how to use the `go/with-cache` command for efficient dependency management and testing in a CircleCI workflow.

```yaml
- checkout
- go/with-cache:
    build: true
    mod: true
    steps:
      - go/mod-download
      - go/test
```

--------------------------------

### with-cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Wraps steps with build, module, and golangci-lint caching capabilities.

```APIDOC
## go/with-cache

### Description
Wraps steps with build, module, and golangci-lint caching capabilities.

### Signature
`go/with-cache`

### Parameters
#### Required Parameters
- **steps** (steps) - Steps to cache

#### Optional Parameters
- **build** (boolean, default: `true`) - Cache build artifacts
- **build-path** (string, default: `~/.cache/go-build`) - Build cache path
- **mod** (boolean, default: `false`) - Cache modules
- **mod-path** (string, default: `~/go/pkg/mod`) - Module cache path
- **golangci-lint** (boolean, default: `false`) - Cache linter
- **golangci-lint-path** (string, default: `~/.cache/golangci-lint`) - Linter cache path
- **key** (string, default: `""`) - Cache key suffix
- **checksum** (string, default: `{{ checksum "go.sum" }}`) - Cache invalidation

### Example
```yaml
go/with-cache:
  build: true
  mod: true
  steps:
    - go/mod-download
    - go/test
```
```

--------------------------------

### Go Orb Test Command with Advanced Options

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Shows how to configure the `go/test` command with advanced options like race detection, coverage mode, timeout, parallelism, build tags, and linker flags.

```yaml
- checkout
- go/test:
    race: true
    covermode: "atomic"
    timeout: "15m"
    parallel: "4"
    build_tags: "integration"
    build_ldflags: "-X 'main.Version=1.0.0'"
```

--------------------------------

### Minimal Go Test

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

A basic CircleCI workflow step to run Go tests.

```yaml
- checkout
- go/test
```

--------------------------------

### Use filepath.Join for Cross-Platform Paths

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Employ `filepath.Join()` from the Go standard library to construct file paths that are compatible across different operating systems, avoiding issues with path separators.

```go
import "path/filepath"
path := filepath.Join("dir", "file.txt")  # Works on all OS
```

--------------------------------

### Manual Approval Workflow for Releases with Go Orb

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

This workflow demonstrates how to implement a manual approval step before releasing to production. It includes a test job, an approval job that filters for tags and ignores branches, and a release job that requires prior approval.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  ci-cd:
    jobs:
      - test
      - approve-release:
          type: approval
          requires:
            - test
          filters:
            tags:
              only: /^v.*/
            branches:
              ignore: /.*/
      - release:
          requires:
            - approve-release
          filters:
            tags:
              only: /^v.*/
            branches:
              ignore: /.*/

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          steps:
            - go/mod-download
            - go/test

  release:
    executor:
      name: go/default
      tag: "1.23"
    environment:
      GITHUB_TOKEN: $GITHUB_TOKEN
    steps:
      - checkout
      - go/install-goreleaser
      - go/goreleaser-release:
          validate-yaml: true
          publish-release: true
```

--------------------------------

### JUnit Output with gotestsum

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Configure CircleCI to generate JUnit XML reports for test results and integrate with CircleCI's test insights. This requires installing `gotestsum` and specifying the `junitfile` parameter.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  test:
    jobs:
      - test

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - run:
          name: Install gotestsum
          command: go install github.com/gotestyourself/gotestsum@latest
      - go/gotestsum:
          packages: "./..."
          junitfile: "test-results.xml"
          coverprofile: "coverage.out"
          covermode: "atomic"
      - store_test_results:
          path: test-results.xml
      - store_artifacts:
          path: coverage.out
```

--------------------------------

### Test Workflow with Caching

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Optimize build times by caching Go modules and build artifacts. This workflow speeds up subsequent builds by reusing previously downloaded dependencies and compiled code.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  test:
    jobs:
      - test

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          steps:
            - go/mod-download
            - go/test
```

--------------------------------

### mod-download

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Runs `go mod download` to download Go modules.

```APIDOC
## go/mod-download

### Description
Runs `go mod download` to download Go modules.

### Signature
`go/mod-download`

### Parameters
None

### Example
```yaml
- go/mod-download
- go/test
```
```

--------------------------------

### Run Tests and Store Coverage Artifacts

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Execute Go tests, generate a coverage profile, and store it as an artifact. This allows for later analysis of code coverage.

```yaml
- go/test:
    coverprofile: "coverage.out"
- store_artifacts:
    path: coverage.out

```

--------------------------------

### Multi-Version Testing

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Set up parallel testing against multiple Go versions using a matrix strategy. Ensure the `go/default` executor and `go/with-cache` are configured correctly for each version.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  test:
    jobs:
      - test:
          matrix:
            parameters: 
              go_version: ["1.22", "1.23"]

jobs:
  test:
    parameters:
      go_version:
        type: string
    executor:
      name: go/default
      tag: << parameters.go_version >>
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          key: "go-<< parameters.go_version >>"
          steps:
            - go/mod-download
            - go/test
```

--------------------------------

### Go Build Cache Key Format

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/architecture.md

Use this format for the build cache. It includes a schema version, a user-configurable key, job name, architecture, a checksum of go.sum, and an epoch for automatic expiration.

```text
v1-<key>-go-build-{{ .Environment.CIRCLE_JOB }}-{{ arch }}-<checksum>-{{ epoch | round "72h" }}
```

--------------------------------

### Cache Go Build and Modules

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Wraps steps with caching for build artifacts and Go modules. Configure which components to cache and their respective paths.

```yaml
go/with-cache:
  build: true
  mod: true
  steps:
    - go/mod-download
    - go/test
```

--------------------------------

### GitHub Release with GoReleaser

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Automate building and publishing multi-platform binaries to GitHub Releases. This requires a GitHub token and a `.goreleaser.yaml` configuration file.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  build-and-release:
    jobs:
      - test:
          filters:
            tags:
              only: /^v.*/
      - release:
          requires:
            - test
          filters:
            tags:
              only: /^v.*/
            branches:
              ignore: /.*/

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          steps:
            - go/mod-download
            - go/test

  release:
    executor:
      name: go/default
      tag: "1.23"
    environment:
      GITHUB_TOKEN: $GITHUB_TOKEN
    steps:
      - checkout
      - go/install-goreleaser:
          version: "v1.24.0"
      - go/goreleaser-release:
          github-token: GITHUB_TOKEN
          project-path: "."
          validate-yaml: true
          publish-release: true
```

```yaml
version: 2
project_name: myapp
builds:
  - id: myapp
    main: ./cmd/myapp
    binary: myapp
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64
    ldflags:
      - -X 'main.Version={{ .Version }}'
      - -X 'main.Commit={{ .Commit }}'
archives:
  - format: tar.gz
    format_overrides:
      - goos: windows
        format: zip
release:
  github:
    owner: your-username
    name: myapp
  prerelease: auto
  draft: false
```

--------------------------------

### Minimal Docker Build Workflow

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Builds a Docker image using multi-stage builds. Requires Docker login credentials and tags the image with the short commit SHA and 'latest'.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  build:
    jobs:
      - build

jobs:
  build:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          steps:
            - run:
                name: Build Docker image
                command: docker build -t myapp:${CIRCLE_SHA1:0:7} .
      - run:
          name: Push Docker image
          command: |
            echo "$DOCKER_PASS" | docker login -u "$DOCKER_USER" --password-stdin
            docker tag myapp:${CIRCLE_SHA1:0:7} myapp:latest
            docker push myapp:${CIRCLE_SHA1:0:7}
            docker push myapp:latest
```

--------------------------------

### Download Go Modules

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Downloads Go modules required for the project. Use this command to ensure all dependencies are fetched.

```yaml
- go/mod-download
- go/test
```

--------------------------------

### Golangci-lint Cache Key Format

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/architecture.md

Use this format for the golangci-lint cache. It follows the same structure as the build cache.

```text
v1-<key>-golangci-lint-{{ .Environment.CIRCLE_JOB }}-{{ arch }}-<checksum>-{{ epoch | round "72h" }}
```

--------------------------------

### Basic Test Workflow

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Run tests on every commit using default CircleCI Go Orb settings. This is a foundational workflow for ensuring code quality.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  test:
    jobs:
      - test

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/test
```

--------------------------------

### Go Orb Test Command Parameters

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Configures the 'go/test' command with various options for running Go tests, including package selection, race detection, timeouts, and coverage reporting.

```yaml
go/test:
  packages: "./..."              # What to test
  race: true                     # Enable race detector
  timeout: "15m"                 # Max test time
  parallel: "4"                  # Build parallelism
  coverprofile: "coverage.out"   # Coverage output
  covermode: "atomic"            # Coverage method
  build_tags: "integration"      # Build tags
  build_ldflags: "-X 'main.V=1'" # Linker flags
```

--------------------------------

### Go Module Cache Key Format

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/architecture.md

Use this format for the module cache. It omits job name and epoch as dependencies change less frequently.

```text
v1-<key>-go-mod-{{ arch }}-<checksum>
```

--------------------------------

### Basic Test Workflow with CircleCI Go Orb

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

A basic CircleCI workflow to test a Go project using the default Go orb executor.

```yaml
version: 2.1

orbs:
  go: circleci/go@1.11.0

workflows:
  test:
    jobs:
      - test

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/test
```

--------------------------------

### Verify Main Go File Existence

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Check if the main Go file exists at the specified path using a simple shell command. This confirms the file is present and accessible.

```bash
ls -la cmd/myapp/main.go
```

--------------------------------

### Go Build and Module Caching Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Configure build and module caching for Go projects. Use 'go.sum' checksum for invalidation. This is the most common and recommended strategy.

```yaml
go/with-cache:
  build: true
  mod: true
  golangci-lint: false
  key: "v1"
  checksum: '{{ checksum "go.sum" }}'
  steps:
    - go/test
```

--------------------------------

### Matrix Build with Multiple Go Versions

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Configures a CircleCI job to run tests against multiple Go versions using a matrix strategy.

```yaml
jobs:
  test:
    parameters:
      go_version:
        type: string
    executor:
      name: go/default
      tag: << parameters.go_version >>
    steps:
      - checkout
      - go/test

workflows:
  test:
    jobs:
      - test:
          matrix:
            parameters:
              go_version: ["1.22", "1.23"]
```

--------------------------------

### with-cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Composite command that wraps provided steps with Go-related caching (build cache, module cache, golangci-lint cache). Loads caches before steps and saves them after.

```APIDOC
## with-cache

### Description
Runs the given steps with Go caching enabled. Supports build cache, module cache, and golangci-lint cache with configurable paths and checksum strategies.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

- **steps** (steps) - Required - The steps to run with caching
- **key** (string) - Optional - User-configurable component for cache key to avoid collisions in complex workflows
- **build** (boolean) - Optional - Whether to use go-build cache
- **build-path** (string) - Optional - Location of go-build cache
- **mod** (boolean) - Optional - Whether to use go module cache (defaults to false because public proxy is usually faster)
- **mod-path** (string) - Optional - Location of go module cache
- **golangci-lint** (boolean) - Optional - Whether to use golangci-lint cache (useful only in linting steps)
- **golangci-lint-path** (string) - Optional - Location of golangci-lint cache
- **checksum** (string) - Optional - Checksum template instruction for cache invalidation

### Request Example
```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          golangci-lint: false
          key: "v1"
          steps:
            - go/mod-download
            - go/test
            - run:
                name: Run linter
                command: golangci-lint run
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### Build Docker Image with Go Cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Build a Docker image for a Go application using the go/with-cache executor. The image is tagged with a short version of the CircleCI SHA.

```yaml
- checkout
- go/with-cache:
    build: true
    steps:
      - run: docker build -t myapp:${CIRCLE_SHA1:0:7} .
```

--------------------------------

### Go Testsum Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Configure the gotestsum command for running tests and generating JUnit XML reports and coverage profiles. Specify packages, output file names, and coverage mode.

```yaml
go/gotestsum:
  packages: "./..."
  junitfile: "test-results/junit.xml"
  coverprofile: "test-results/coverage.out"
  covermode: "atomic"
```

--------------------------------

### Custom Go Build Workflow

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Perform custom build steps within a CircleCI workflow using the `go/with-cache` executor. This allows for building multiple executables or custom tools.

```yaml
go/with-cache:
  build: true
  steps:
    - run:
        name: Custom build
        command: |
          go build -o bin/app ./cmd/app
          go build -o bin/tool ./cmd/tool
```

--------------------------------

### Go Test Command Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Configures the 'go test' command with various options such as race detection, coverage settings, timeouts, and parallel execution. The 'covermode' must be 'atomic' when '-race' is enabled.

```yaml
go/test:
  race: true
  covermode: "atomic"
  timeout: "15m"
  parallel: "4"
  build_tags: "integration,e2e"
  build_ldflags: "-X 'main.Version=1.0.0'"
```

--------------------------------

### Configure GoReleaser Build Main Package Path

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Specify the path to the main Go package within your project's configuration. This ensures GoReleaser can locate the entry point for your application build.

```yaml
builds:
  - main: ./cmd/myapp
    binary: myapp
```

--------------------------------

### GoReleaser Release Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Configure the `go/goreleaser-release` command to build and publish releases to GitHub. Specify the GitHub token, project path, and whether to publish or create a snapshot.

```yaml
go/goreleaser-release:
  github-token: GITHUB_TOKEN
  project-path: "."
  validate-yaml: true
  publish-release: true
```

--------------------------------

### Configure Go Orb for Monorepo Project Path

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Use the 'project-path' parameter with Go Orb commands to specify a subdirectory for monorepos.

```yaml
go/test:
  project-path: "./services/api"
```

--------------------------------

### Custom Project Path for Testing

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Runs Go tests for an application located in a subdirectory. Specify the project path within the `go/test` command.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  test:
    jobs:
      - test

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/with-cache:
          build: true
          mod: true
          steps:
            - go/mod-download
            - go/test:
                project-path: "./services/api"
```

--------------------------------

### Enable Go Test Short Mode

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Run Go tests in 'short' mode, which typically skips longer-running tests. This is useful for faster feedback loops during development.

```yaml
go/test:
  short: true
```

--------------------------------

### Check GoReleaser Configuration Locally

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Run the `goreleaser check` command directly in your local environment to validate the `.goreleaser.yaml` configuration file. This helps identify syntax errors or missing fields before committing.

```bash
goreleaser check
```

--------------------------------

### Download Go Modules with Cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Downloads Go modules and caches them, following a load-download-save cycle. This optimizes subsequent builds by reusing cached modules.

```yaml
- go/mod-download-cached
- go/test
```

--------------------------------

### Go Test with Caching

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Integrates Go module caching into the testing workflow for faster builds.

```yaml
- checkout
- go/with-cache:
    steps:
      - go/mod-download
      - go/test
```

--------------------------------

### Snapshot Release Workflow

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

Use this workflow to test the GoReleaser build process without actually publishing a release. It checks YAML validation and skips the publish step.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  snapshot:
    jobs:
      - snapshot

jobs:
  snapshot:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/install-goreleaser
      - go/goreleaser-release:
          validate-yaml: true
          publish-release: false
      - store_artifacts:
          path: dist/
```

--------------------------------

### Enable Module Cache for Internal Dependencies or Slow Networks

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Use the `go/with-cache` orb with `mod: true` to cache Go modules. This is beneficial for projects with many internal dependencies or slow network connections.

```yaml
go/with-cache:
  mod: true
  steps:
    - go/mod-download
```

--------------------------------

### Store Go Test Coverage Artifact

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

After generating a coverage profile, use the 'store_artifacts' command to save the coverage file. This allows you to view and analyze the coverage report.

```yaml
- store_artifacts:
    path: coverage.out
```

--------------------------------

### Enable Go Build and Module Caching

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Enable caching for Go builds and module dependencies to speed up subsequent runs. Use this when you want to leverage CircleCI's caching mechanisms for your Go project.

```yaml
go/with-cache:
  build: true
  mod: true
```

--------------------------------

### Enable Caching with Go Orb

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Use the `go/with-cache` executor to enable caching for your Go builds. Set `build: true` to cache build artifacts and `mod: false` if module caching is not needed.

```yaml
go/with-cache:
    build: true
    mod: false  # Only if needed
    steps:
      - go/test
```

--------------------------------

### Go Test with Race Detection

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Enables race detection and sets covermode to 'atomic' for more thorough Go testing.

```yaml
- checkout
- go/test:
    race: true
    covermode: "atomic"
```

--------------------------------

### Performance-Optimized Workflow with Go Orb

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/examples-workflows.md

This workflow maximizes caching and parallel execution for Go projects. It configures Go build and module caching, and enables parallel testing with race detection and coverage.

```yaml
version: 2.1

orbs:
  go: circleci/go@x.y

workflows:
  test:
    jobs:
      - test

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    environment:
      GOMAXPROCS: "4"
    steps:
      - checkout
      - go/with-cache:
          build: true
          build-path: ~/.cache/go-build
          mod: true
          mod-path: ~/go/pkg/mod
          key: "perf-v1"
          steps:
            - go/mod-download-cached
            - go/test:
                parallel: "4"
                parallel-tests: "4"
                timeout: "20m"
                race: true
                covermode: "atomic"
```

--------------------------------

### Use Automatic Parallelism with Go Orb

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Configure `go/test` to use automatic parallelism based on the number of available CPUs. Set `parallel` and `parallel-tests` to 'm' for optimal performance.

```yaml
go/test:
  parallel: "m"  # Use GOMAXPROCS (recommended)
  parallel-tests: "m"
```

--------------------------------

### Ensure Go Module Download Before Testing

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

To resolve 'module not found' errors, ensure that Go modules are downloaded before running tests. This can be done using 'go/mod-download' or 'go/mod-download-cached'.

```yaml
- go/mod-download
- go/test
```

```yaml
- go/mod-download-cached
- go/test
```

--------------------------------

### load-build-cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Restores cached Go build artifacts using a specified key and checksum for validation.

```APIDOC
## go/load-build-cache

### Description
Restores cached Go build artifacts using a specified key and checksum for validation.

### Signature
`go/load-build-cache`

### Parameters
#### Optional Parameters
- **key** (string, default: `""`) - Cache key suffix
- **checksum** (string, default: `{{ checksum "go.sum" }}`) - Cache validation

### Example
```yaml
- go/load-build-cache:
    key: "v1"
```
```

--------------------------------

### Configure arm64 Executor with Timeout

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Specify the `macos.m1` resource class for arm64 builds and set a longer `timeout` for the `go/test` job to accommodate potential performance differences.

```yaml
jobs:
  test:
    resource_class: macos.m1  # arm64
    steps:
      - go/test:
          timeout: "20m"
```

--------------------------------

### Default Go Executor Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/configuration.md

Specifies the Go Docker image and tag to use for the executor. Ensure the tag corresponds to a supported Go version.

```yaml
executor:
  name: go/default
  tag: "1.23"
```

--------------------------------

### load-build-cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Restores cached Go build artifacts from CircleCI cache. It uses a key and checksum for validation and automatically expires caches every 72 hours.

```APIDOC
## load-build-cache

### Description
Restores cached Go build artifacts from CircleCI cache.

### Parameters
#### Query Parameters
- **key** (string) - Optional - User-configurable component for cache key to avoid collisions. Defaults to an empty string.
- **checksum** (string) - Optional - Checksum template instruction for cache validation. Defaults to `{{ checksum "go.sum" }}`.

### Cache Key Format
`v1-<key>-go-build-{{ .Environment.CIRCLE_JOB }}-{{ arch }}-<checksum>-{{ epoch | round "72h" }}`

### Note
Cache key includes 72-hour epoch rounding to expire caches automatically every 72 hours.

### Usage Example
```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/load-build-cache
```
```

--------------------------------

### Cache Build and Module Dependencies

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Utilize the go/with-cache job to cache both build artifacts and Go module dependencies. This speeds up subsequent builds by reusing cached components.

```yaml
- go/with-cache:
    build: true
    mod: true
    steps:
      - go/mod-download
      - go/test

```

--------------------------------

### Test Multiple Go Versions using Matrix

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/README.md

Configure a CircleCI workflow to test your Go project against multiple Go versions using a matrix strategy. This ensures compatibility across different Go environments.

```yaml
jobs:
  test:
    parameters:
      go_version: {type: string}
    executor:
      name: go/default
      tag: << parameters.go_version >>
    steps:
      - checkout
      - go/test

workflows:
  test:
    jobs:
      - test:
          matrix:
            parameters:
              go_version: ["1.22", "1.23"]

```

--------------------------------

### load-mod-cache

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/api-reference.md

Restores cached Go module dependencies from CircleCI cache.

```APIDOC
## load-mod-cache

### Description
Load cached Go modules.

### Method
None explicitly documented.

### Endpoint
None explicitly documented.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

- **key** (string) - Optional - User-configurable component for cache key to avoid collisions
- **checksum** (string) - Optional - Checksum template instruction for cache validation

### Request Example
```yaml
version: 2.1
orbs:
  go: circleci/go@x.y

jobs:
  build:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/load-mod-cache:
          key: "v1"
          checksum: '{{ checksum "go.sum" }}'
```

### Response
#### Success Response (200)
None explicitly documented.

#### Response Example
None explicitly documented.
```

--------------------------------

### Add Go Orb to CircleCI Configuration

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Include this snippet in your .circleci/config.yml to integrate the Go orb. Replace the version with the latest release.

```yaml
version: 2.1

orbs:
  go: circleci/go@1.11.0  # or latest version

jobs:
  test:
    executor:
      name: go/default
      tag: "1.23"
    steps:
      - checkout
      - go/test
```

--------------------------------

### Environment-Based Configuration for Testing

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/architecture.md

Dynamically set test parameters like parallelism and timeout based on pipeline parameters. This enables environment-specific test configurations.

```yaml
go/test:
  parallel: << pipeline.parameters.parallelism >>
  timeout: << pipeline.parameters.test_timeout >>
```

--------------------------------

### Execute Go Tests with Race Detector and Coverage

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/command-reference.md

Executes `go test` with the race detector enabled and coverage reporting configured. Useful for identifying concurrency issues and measuring test coverage.

```yaml
go/test:
  race: true
  covermode: "atomic"
  timeout: "15m"
  parallel: "4"
```

--------------------------------

### Ensure Cache Usage in Build Steps

Source: https://github.com/circleci-public/go-orb/blob/master/_autodocs/faq-troubleshooting.md

Configure the `go/with-cache` orb to use the cache during build steps. Set `build: true` to enable cache restoration for build artifacts.

```yaml
- go/with-cache:
    build: true
    steps:
      - run: go build ./...
```