Introduction

This guide shows you how to build, test, and publish a Go package.

GitHub-hosted runners have a tools cache with preinstalled software, which includes the dependencies for Go. For a full list of up-to-date software and the preinstalled versions of Go, seeGitHub-hosted runners.

Prerequisites

You should already be familiar with YAML syntax and how it's used with GitHub Actions. For more information, seeWorkflow syntax for GitHub Actions.

We recommend that you have a basic understanding of the Go language. For more information, seeGetting started with Go.

Using a Go workflow template

To get started quickly, add a workflow template to the.github/workflows directory of your repository.

GitHub provides a Go workflow template that should work for most Go projects. The subsequent sections of this guide give examples of how you can customize this workflow template.

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Actions.

   

3. If you already have a workflow in your repository, clickNew workflow.

4. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "go".

5. Filter the selection of workflows by clickingContinuous integration.

6. On the "Go - by GitHub Actions" workflow, clickConfigure.

   

7. Edit the workflow as required. For example, change the version of Go.

8. ClickCommit changes.

   Thego.yml workflow file is added to the.github/workflows directory of your repository.

Specifying a Go version

The easiest way to specify a Go version is by using thesetup-go action provided by GitHub. For more information see, thesetup-go action.

To use a preinstalled version of Go on a GitHub-hosted runner, pass the relevant version to thego-version property of thesetup-go action. This action finds a specific version of Go from the tools cache on each runner, and adds the necessary binaries toPATH. These changes will persist for the remainder of the job.

Thesetup-go action is the recommended way of using Go with GitHub Actions, because it helps ensure consistent behavior across different runners and different versions of Go. If you are using a self-hosted runner, you must install Go and add it toPATH.

Using multiple versions of Go

name: Goon: [push]jobs:  build:    runs-on: ubuntu-latest    strategy:      matrix:        go-version: [ '1.19', '1.20', '1.21.x' ]    steps:      - uses: actions/checkout@v5      - name: Setup Go ${{ matrix.go-version }}        uses: actions/setup-go@v5        with:          go-version: ${{ matrix.go-version }}      # You can test your matrix by printing the current Go version      - name: Display Go version        run: go version

name:Goon: [push]jobs:build:runs-on:ubuntu-lateststrategy:matrix:go-version: ['1.19','1.20','1.21.x' ]steps:-uses:actions/checkout@v5-name:SetupGo${{matrix.go-version}}uses:actions/setup-go@v5with:go-version:${{matrix.go-version}}# You can test your matrix by printing the current Go version-name:DisplayGoversionrun:goversion

Using a specific Go version

You can configure your job to use a specific version of Go, such as1.20.8. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest patch release of Go 1.21:

      - name: Setup Go 1.21.x        uses: actions/setup-go@v5        with:          # Semantic version range syntax or exact version of Go          go-version: '1.21.x'

-name:SetupGo1.21.xuses:actions/setup-go@v5with:# Semantic version range syntax or exact version of Gogo-version:'1.21.x'

Installing dependencies

You can usego get to install dependencies:

    steps:      - uses: actions/checkout@v5      - name: Setup Go        uses: actions/setup-go@v5        with:          go-version: '1.21.x'      - name: Install dependencies        run: |          go get .          go get example.com/octo-examplemodule          go get example.com/octo-examplemodule@v1.3.4

steps:-uses:actions/checkout@v5-name:SetupGouses:actions/setup-go@v5with:go-version:'1.21.x'-name:Installdependenciesrun:|          go get .          go get example.com/octo-examplemodule          go get example.com/octo-examplemodule@v1.3.4

Caching dependencies

You can cache and restore dependencies using thesetup-go action. By default, caching is enabled when using thesetup-go action.

Thesetup-go action searches for the dependency file,go.sum, in the repository root and uses the hash of the dependency file as a part of the cache key.

You can use thecache-dependency-path parameter for cases when multiple dependency files are used, or when they are located in different subdirectories.

      - name: Setup Go        uses: actions/setup-go@v5        with:          go-version: '1.17'          cache-dependency-path: subdir/go.sum

-name:SetupGouses:actions/setup-go@v5with:go-version:'1.17'cache-dependency-path:subdir/go.sum

If you have a custom requirement or need finer controls for caching, you can use thecache action. For more information, seeDependency caching reference.

Building and testing your code

You can use the same commands that you use locally to build and test your code. This example workflow demonstrates how to usego build andgo test in a job:

name: Goon: [push]jobs:  build:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v5      - name: Setup Go        uses: actions/setup-go@v5        with:          go-version: '1.21.x'      - name: Install dependencies        run: go get .      - name: Build        run: go build -v ./...      - name: Test with the Go CLI        run: go test

name:Goon: [push]jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:SetupGouses:actions/setup-go@v5with:go-version:'1.21.x'-name:Installdependenciesrun:goget.-name:Buildrun:gobuild-v./...-name:TestwiththeGoCLIrun:gotest

Packaging workflow data as artifacts

After a workflow completes, you can upload the resulting artifacts for analysis. For example, you may need to save log files, core dumps, test results, or screenshots. The following example demonstrates how you can use theupload-artifact action to upload test results.

For more information, seeStore and share data with workflow artifacts.

name: Upload Go test resultson: [push]jobs:  build:    runs-on: ubuntu-latest    strategy:      matrix:        go-version: [ '1.19', '1.20', '1.21.x' ]    steps:      - uses: actions/checkout@v5      - name: Setup Go        uses: actions/setup-go@v5        with:          go-version: ${{ matrix.go-version }}      - name: Install dependencies        run: go get .      - name: Test with Go        run: go test -json > TestResults-${{ matrix.go-version }}.json      - name: Upload Go test results        uses: actions/upload-artifact@v4        with:          name: Go-results-${{ matrix.go-version }}          path: TestResults-${{ matrix.go-version }}.json

name:UploadGotestresultson: [push]jobs:build:runs-on:ubuntu-lateststrategy:matrix:go-version: ['1.19','1.20','1.21.x' ]steps:-uses:actions/checkout@v5-name:SetupGouses:actions/setup-go@v5with:go-version:${{matrix.go-version}}-name:Installdependenciesrun:goget.-name:TestwithGorun:gotest-json>TestResults-${{matrix.go-version}}.json-name:UploadGotestresultsuses:actions/upload-artifact@v4with:name:Go-results-${{matrix.go-version}}path:TestResults-${{matrix.go-version}}.json