{"meta":{"title":"Building and testing Go","intro":"Learn how to create a continuous integration (CI) workflow to build and test your Go project.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/actions","title":"GitHub Actions"},{"href":"/en/enterprise-cloud@latest/actions/tutorials","title":"Tutorials"},{"href":"/en/enterprise-cloud@latest/actions/tutorials/build-and-test-code","title":"Build and test code"},{"href":"/en/enterprise-cloud@latest/actions/tutorials/build-and-test-code/go","title":"Go"}],"documentType":"article"},"body":"# Building and testing Go\n\nLearn how to create a continuous integration (CI) workflow to build and test your Go project.\n\n## Introduction\n\nThis guide shows you how to build, test, and publish a Go package.\n\nGitHub-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, see [GitHub-hosted runners](/en/enterprise-cloud@latest/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software).\n\n## Prerequisites\n\nYou should already be familiar with YAML syntax and how it's used with GitHub Actions. For more information, see [Workflow syntax for GitHub Actions](/en/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions).\n\nWe recommend that you have a basic understanding of the Go language. For more information, see [Getting started with Go](https://golang.org/doc/tutorial/getting-started).\n\n## Using a Go workflow template\n\nTo get started quickly, add a workflow template to the `.github/workflows` directory of your repository.\n\nGitHub 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.\n\n1. On GitHub, navigate to the main page of the repository.\n\n2. Under your repository name, click ** Actions**.\n\n ![Screenshot of the tabs for the \"github/docs\" repository. The \"Actions\" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab-global-nav-update.png)\n\n3. If you already have a workflow in your repository, click **New workflow**.\n\n4. The \"Choose a workflow\" page shows a selection of recommended workflow templates. Search for \"go\".\n\n5. Filter the selection of workflows by clicking **Continuous integration**.\n\n6. On the \"Go - by GitHub Actions\" workflow, click **Configure**.\n\n ![Screenshot of the \"Choose a workflow\" page. The \"Configure\" button on the \"Go\" workflow is highlighted with an orange outline.](/assets/images/help/actions/starter-workflow-go.png)\n\n7. Edit the workflow as required. For example, change the version of Go.\n\n8. Click **Commit changes**.\n\n The `go.yml` workflow file is added to the `.github/workflows` directory of your repository.\n\n## Specifying a Go version\n\nThe easiest way to specify a Go version is by using the `setup-go` action provided by GitHub. For more information see, the [`setup-go` action](https://github.com/actions/setup-go/).\n\nTo use a preinstalled version of Go on a GitHub-hosted runner, pass the relevant version to the `go-version` property of the `setup-go` action. This action finds a specific version of Go from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job.\n\nThe `setup-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 to `PATH`.\n\n### Using multiple versions of Go\n\n```yaml copy\nname: Go\n\non: [push]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n strategy:\n matrix:\n go-version: [ '1.19', '1.20', '1.21.x' ]\n\n steps:\n - uses: actions/checkout@v6\n - name: Setup Go ${{ matrix.go-version }}\n uses: actions/setup-go@v5\n with:\n go-version: ${{ matrix.go-version }}\n # You can test your matrix by printing the current Go version\n - name: Display Go version\n run: go version\n```\n\n### Using a specific Go version\n\nYou can configure your job to use a specific version of Go, such as `1.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:\n\n```yaml copy\n - name: Setup Go 1.21.x\n uses: actions/setup-go@v5\n with:\n # Semantic version range syntax or exact version of Go\n go-version: '1.21.x'\n```\n\n## Installing dependencies\n\nYou can use `go get` to install dependencies:\n\n```yaml copy\n steps:\n - uses: actions/checkout@v6\n - name: Setup Go\n uses: actions/setup-go@v5\n with:\n go-version: '1.21.x'\n - name: Install dependencies\n run: |\n go get .\n go get example.com/octo-examplemodule\n go get example.com/octo-examplemodule@v1.3.4\n```\n\n### Caching dependencies\n\nYou can cache and restore dependencies using the [`setup-go` action](https://github.com/actions/setup-go). By default, caching is enabled when using the `setup-go` action.\n\nThe `setup-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.\n\nYou can use the `cache-dependency-path` parameter for cases when multiple dependency files are used, or when they are located in different subdirectories.\n\n```yaml copy\n - name: Setup Go\n uses: actions/setup-go@v5\n with:\n go-version: '1.17'\n cache-dependency-path: subdir/go.sum\n```\n\nIf you have a custom requirement or need finer controls for caching, you can use the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [Dependency caching reference](/en/enterprise-cloud@latest/actions/using-workflows/caching-dependencies-to-speed-up-workflows).\n\n## Building and testing your code\n\nYou can use the same commands that you use locally to build and test your code. This example workflow demonstrates how to use `go build` and `go test` in a job:\n\n```yaml copy\nname: Go\non: [push]\n\njobs:\n build:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v6\n - name: Setup Go\n uses: actions/setup-go@v5\n with:\n go-version: '1.21.x'\n - name: Install dependencies\n run: go get .\n - name: Build\n run: go build -v ./...\n - name: Test with the Go CLI\n run: go test\n```\n\n## Packaging workflow data as artifacts\n\nAfter 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 the `upload-artifact` action to upload test results.\n\nFor more information, see [Store and share data with workflow artifacts](/en/enterprise-cloud@latest/actions/using-workflows/storing-workflow-data-as-artifacts).\n\n```yaml copy\nname: Upload Go test results\n\non: [push]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n strategy:\n matrix:\n go-version: [ '1.19', '1.20', '1.21.x' ]\n\n steps:\n - uses: actions/checkout@v6\n - name: Setup Go\n uses: actions/setup-go@v5\n with:\n go-version: ${{ matrix.go-version }}\n - name: Install dependencies\n run: go get .\n - name: Test with Go\n run: go test -json > TestResults-${{ matrix.go-version }}.json\n - name: Upload Go test results\n uses: actions/upload-artifact@v4\n with:\n name: Go-results-${{ matrix.go-version }}\n path: TestResults-${{ matrix.go-version }}.json\n```"}