setup-go

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

🚨 Breaking Changes in V6

Critical Requirements

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

Enhanced Go Toolchain Management

V6 introduces significant improvements to ensure reliable and consistent Go version selection:

1. Toolchain Directive Support

Now correctly interprets both go and toolchain directives from go.mod:

go 1.21.0           // Minimum required version
toolchain go1.21.6  // V6 uses this exact version

2. Advanced Version Resolution

Supports comprehensive version patterns:

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

3. Intelligent Caching

• Cache keys now incorporate toolchain-specific metadata
• Eliminates version conflicts when switching between Go versions
• Improved workflow reliability

Migration Benefits

✅ Exact Go version matching
✅ Improved build reproducibility
✅ Reduced version-related issues

For more details, see the full release notes.

---

📋 Previous Versions

V5 Changes

• Upgraded Node.js runtime from node16 to node20
• See full V5 release notes

---

🚀 Usage

See action.yml

Basic Setup

steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: '1.16.1' # The Go version to download (if necessary) and use.
  - run: go run hello.go

Version Selection Examples

Using Semantic Versioning

# Caret notation (minor updates)
steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: '^1.13.1'
  - run: go version

# 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:

go-version: '1.20'  # ✅ Correct
go-version: 1.20    # ❌ Incorrect - YAML interprets as 1.2

Pre-release Versions

# RC version
steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: '1.18.0-rc.1'
  - run: go version

# 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.

steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: '1.14'
      check-latest: true
  - run: go run hello.go

Note: Setting check-latest: true has performance implications as downloading Go versions is slower than using cached versions.

Using Stable/Oldstable Aliases

# Latest stable version
steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: 'stable'
  - run: go run hello.go

# Previous stable version
steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: 'oldstable'
  - run: go run hello.go

Note: Using these aliases will result in the same version as using the corresponding minor release with check-latest: true

Caching Dependencies and Build Outputs

The action has built-in functionality for caching and restoring go modules and build outputs. Caching is enabled by default.

Caching in Monorepos

steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version: '1.17'
      check-latest: true
      cache-dependency-path: |
        subdir/go.sum
        tools/go.sum        
      # Alternative: cache-dependency-path: "**/*.sum"
  - run: go run hello.go

Getting Go Version from go.mod

The action can read the Go version directly from your go.mod or go.work file:

steps:
  - uses: actions/checkout@v5
  - uses: actions/setup-go@v6
    with:
      go-version-file: 'path/to/go.mod'
  - run: go version

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

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        go: [ '1.14', '1.13' ]
    name: Go ${{ matrix.go }} sample
    steps:
      - uses: actions/checkout@v5
      - name: Setup go
        uses: actions/setup-go@v6
        with:
          go-version: ${{ matrix.go }}
      - run: go run hello.go

---

📝 Supported Version Syntax

The go-version input supports:

• 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

For more information about semantic versioning, please refer to semver documentation.

---

🏢 Using setup-go on GHES

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:

uses: actions/setup-go@v6
with:
  token: ${{ secrets.GH_DOTCOM_TOKEN }}
  go-version: '1.18'

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" for more information.

---

🔒 Recommended Permissions

When using the setup-go action in your GitHub Actions workflow, set the following permissions:

permissions:
  contents: read  # access to check out code and install dependencies

---

⚙️ 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

🤝 Contributions

Contributions are welcome! See Contributor's Guide

👮 Code of Conduct

👋 Be nice. See our code of conduct