Skip to content

Commit 1620a0b

Browse files
sampartlucascosti
sampart
and
lucascosti
authored
Add "Building and testing Go" (#28564)
Co-authored-by: Lucas Costi <[email protected]>
1 parent 964b20a commit 1620a0b

File tree

3 files changed

+225
-26
lines changed

3 files changed

+225
-26
lines changed

‎content/actions/automating-builds-and-tests/building-and-testing-go.md

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
title: Building and testing Go
3+
intro: You can create a continuous integration (CI) workflow to build and test your Go project.
4+
versions:
5+
fpt: '*'
6+
ghes: '*'
7+
ghae: '*'
8+
ghec: '*'
9+
type: tutorial
10+
topics:
11+
- CI
12+
shortTitle: Build & test Go
13+
---
14+
15+
{% data reusables.actions.enterprise-beta %}
16+
{% data reusables.actions.enterprise-github-hosted-runners %}
17+
18+
## Introduction
19+
20+
This guide shows you how to build, test, and publish a Go package.
21+
22+
{% ifversion ghae %}
23+
{% data reusables.actions.self-hosted-runners-software %}
24+
{% else %} {% data variables.product.prodname_dotcom %}-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 "[About {% data variables.product.prodname_dotcom %}-hosted runners](/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software)."
25+
{% endif %}
26+
27+
## Prerequisites
28+
29+
You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/using-workflows/workflow-syntax-for-github-actions)."
30+
31+
We 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).
32+
33+
## Using the Go starter workflow
34+
35+
{% data variables.product.prodname_dotcom %} provides a Go starter workflow that should work for most Go projects. This guide includes examples that you can use to customize the starter workflow. For more information, see the [Go starter workflow](https://github.com/actions/starter-workflows/blob/main/ci/go.yml).
36+
37+
To get started quickly, add the starter workflow to the `.github/workflows` directory of your repository.
38+
39+
```yaml{:copy}
40+
name: Go package
41+
42+
on: [push]
43+
44+
jobs:
45+
build:
46+
47+
runs-on: ubuntu-latest
48+
steps:
49+
- uses: {% data reusables.actions.action-checkout %}
50+
51+
- name: Set up Go
52+
uses: {% data reusables.actions.action-setup-go %}
53+
with:
54+
go-version: 1.15
55+
56+
- name: Build
57+
run: go build -v ./...
58+
59+
- name: Test
60+
run: go test -v ./...
61+
```
62+
63+
## Specifying a Go version
64+
65+
The easiest way to specify a Go version is by using the `setup-go` action provided by {% data variables.product.prodname_dotcom %}. For more information see, the [`setup-go` action](https://github.com/actions/setup-go/).
66+
67+
To use a preinstalled version of Go on a {% data variables.product.prodname_dotcom %}-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.
68+
69+
The `setup-go` action is the recommended way of using Go with {% data variables.product.prodname_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`.
70+
71+
### Using multiple versions of Go
72+
73+
```yaml{:copy}
74+
name: Go
75+
76+
on: [push]
77+
78+
jobs:
79+
build:
80+
81+
runs-on: ubuntu-latest
82+
strategy:
83+
matrix:
84+
go-version: [ '1.14', '1.15', '1.16.x' ]
85+
86+
steps:
87+
- uses: {% data reusables.actions.action-checkout %}
88+
- name: Setup Go {% raw %}${{ matrix.go-version }}{% endraw %}
89+
uses: {% data reusables.actions.action-setup-go %}
90+
with:
91+
go-version: {% raw %}${{ matrix.go-version }}{% endraw %}
92+
# You can test your matrix by printing the current Go version
93+
- name: Display Go version
94+
run: go version
95+
```
96+
97+
### Using a specific Go version
98+
99+
You can configure your job to use a specific version of Go, such as `1.16.2`. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest patch release of Go 1.16:
100+
101+
```yaml{:copy}
102+
- name: Setup Go 1.16.x
103+
uses: {% data reusables.actions.action-setup-go %}
104+
with:
105+
# Semantic version range syntax or exact version of Go
106+
go-version: '1.16.x'
107+
```
108+
109+
## Installing dependencies
110+
111+
You can use `go get` to install dependencies:
112+
113+
```yaml{:copy}
114+
steps:
115+
- uses: {% data reusables.actions.action-checkout %}
116+
- name: Setup Go
117+
uses: {% data reusables.actions.action-setup-go %}
118+
with:
119+
go-version: '1.16.x'
120+
- name: Install dependencies
121+
run: |
122+
go get .
123+
go get example.lab/octo-examplemodule
124+
go get example.lab/[email protected]
125+
```
126+
127+
{% ifversion actions-caching %}
128+
129+
### Caching dependencies
130+
131+
You can cache and restore the dependencies using the [`setup-go` action](https://github.com/actions/setup-go). By default, caching is disabled, but you can set the `cache` parameter to `true` to enable it.
132+
133+
When caching is enabled, the `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.
134+
135+
```yaml{:copy}
136+
- name: Setup Go
137+
uses: {% data reusables.actions.action-setup-go %}
138+
with:
139+
go-version: '1.16.x'
140+
cache: true
141+
```
142+
143+
Alternatively, you can use the `cache-dependency-path` parameter for cases when multiple dependency files are used, or when they are located in different subdirectories.
144+
145+
```yaml{:copy}
146+
- uses: {% data reusables.actions.action-setup-go %}
147+
with:
148+
go-version: '1.17'
149+
cache: true
150+
cache-dependency-path: subdir/go.sum
151+
```
152+
153+
If 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 "[Caching dependencies to speed up workflows](/actions/using-workflows/caching-dependencies-to-speed-up-workflows)."
154+
155+
{% endif %}
156+
157+
## Building and testing your code
158+
159+
You 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:
160+
161+
```yaml{:copy}
162+
name: Go
163+
on: [push]
164+
165+
jobs:
166+
build:
167+
runs-on: ubuntu-latest
168+
169+
steps:
170+
- uses: {% data reusables.actions.action-checkout %}
171+
- name: Setup Go
172+
uses: {% data reusables.actions.action-setup-go %}
173+
with:
174+
go-version: '1.16.x'
175+
- name: Install dependencies
176+
run: go get .
177+
- name: Build
178+
run: go build -v ./...
179+
- name: Test with the Go CLI
180+
run: go test
181+
```
182+
183+
## Packaging workflow data as artifacts
184+
185+
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 the `upload-artifact` action to upload test results.
186+
187+
For more information, see "[Storing workflow data as artifacts](/actions/using-workflows/storing-workflow-data-as-artifacts)."
188+
189+
```yaml{:copy}
190+
name: Upload Go test results
191+
192+
on: [push]
193+
194+
jobs:
195+
build:
196+
197+
runs-on: ubuntu-latest
198+
strategy:
199+
matrix:
200+
go-version: [ '1.14', '1.15', '1.16.x' ]
201+
202+
steps:
203+
- uses: {% data reusables.actions.action-checkout %}
204+
- name: Setup Go
205+
uses: {% data reusables.actions.action-setup-go %}
206+
with:
207+
go-version: {% raw %}${{ matrix.go-version }}{% endraw %}
208+
- name: Install dependencies
209+
run: go get .
210+
- name: Test with Go
211+
run: go test -json > TestResults-{% raw %}${{ matrix.go-version }}{% endraw %}.json
212+
- name: Upload Go test results
213+
uses: {% data reusables.actions.action-upload-artifact %}
214+
with:
215+
name: Go-results-{% raw %}${{ matrix.go-version }}{% endraw %}
216+
path: TestResults-{% raw %}${{ matrix.go-version }}{% endraw %}.json
217+
```

‎content/actions/automating-builds-and-tests/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ redirect_from:
1818
- /actions/automating-builds-and-tests/building-and-testing-nodejs-or-python
1919
children:
2020
- /about-continuous-integration
21+
- /building-and-testing-go
2122
- /building-and-testing-java-with-ant
2223
- /building-and-testing-java-with-gradle
2324
- /building-and-testing-java-with-maven

‎content/actions/using-workflows/caching-dependencies-to-speed-up-workflows.md

Lines changed: 7 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -24,32 +24,13 @@ Workflow runs often reuse the same outputs or downloaded dependencies from one r
2424

2525
To cache dependencies for a job, you can use {% data variables.product.prodname_dotcom %}'s [`cache` action](https://github.com/actions/cache). The action creates and restores a cache identified by a unique key. Alternatively, if you are caching the package managers listed below, using their respective setup-* actions requires minimal configuration and will create and restore dependency caches for you.
2626

27-
<table>
28-
<thead>
29-
<tr>
30-
<th>Package managers</th>
31-
<th>setup-* action for caching</th>
32-
</tr>
33-
</thead>
34-
<tbody>
35-
<tr>
36-
<td>npm, yarn, pnpm</td>
37-
<td><a href="https://github.com/actions/setup-node#caching-global-packages-data">setup-node</a></td>
38-
</tr>
39-
<tr>
40-
<td>pip, pipenv, poetry</td>
41-
<td><a href="https://github.com/actions/setup-python#caching-packages-dependencies">setup-python</a></td>
42-
</tr>
43-
<tr>
44-
<td>gradle, maven</td>
45-
<td><a href="https://github.com/actions/setup-java#caching-packages-dependencies">setup-java</a></td>
46-
</tr>
47-
<tr>
48-
<td>ruby gems</td>
49-
<td><a href="https://github.com/ruby/setup-ruby#caching-bundle-install-automatically">setup-ruby</a></td>
50-
</tr>
51-
</tbody>
52-
</table>
27+
| Package managers | setup-* action for caching |
28+
|---|---|
29+
| npm, Yarn, pnpm | [setup-node](https://github.com/actions/setup-node#caching-global-packages-data) |
30+
| pip, pipenv, Poetry | [setup-python](https://github.com/actions/setup-python#caching-packages-dependencies) |
31+
| Gradle, Maven | [setup-java](https://github.com/actions/setup-java#caching-packages-dependencies) |
32+
| RubyGems | [setup-ruby](https://github.com/ruby/setup-ruby#caching-bundle-install-automatically) |
33+
| Go `go.sum` | [setup-go](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs) |
5334

5435
{% warning %}
5536

0 commit comments

Comments
 (0)