CI for a Go project
A Go project needs little continuous integration: one installation of the toolchain, three commands, and a cache for the modules. The previous lesson laid out the module; this one runs its checks on a machine that is not yours. The point of the job is not to repeat what a developer does but to run exactly the same commands with nothing left out, so a difference between the laptop and the runner is a bug in the job.
The loop on your machine
The package below is a module with two exported functions and a main that uses them. A local run of gofmt, go vet and go build is what the job repeats, and each of the three has an exit status the shell can test: gofmt -l prints the files it would change and exits 0 either way, so the check is that its output is empty.
package main
import (
"fmt"
"os"
)
// Sum adds the numbers it is given.
func Sum(numbers ...int) int {
total := 0
for _, n := range numbers {
total += n
}
return total
}
// Average returns the mean of the numbers, or 0 for none.
func Average(numbers ...int) float64 {
if len(numbers) == 0 {
return 0
}
return float64(Sum(numbers...)) / float64(len(numbers))
}
func main() {
fmt.Printf("sum: %d\n", Sum(1, 2, 3))
fmt.Printf("average: %.2f\n", Average(1, 2, 4))
os.Exit(0)
}
gofmt -l . && echo "gofmt: clean"
go vet ./... && echo "vet: clean"
go build -o app . && ./app
gofmt: clean
vet: clean
sum: 6
average: 2.33
The three commands are the whole pre-commit loop of a small package. gofmt is silent when every file is formatted, vet prints nothing when it has no finding, and the binary ran. A job that runs these on every push catches the formatting that slipped through an editor and the format string that vet reads.
What the job runs
The test file sits in the same package and checks the exported functions through the same names main uses. go test -v ./... builds the package with the test files, runs every Test function and prints one line per test. The last line is the package summary: ok and the time it took.
package main
import "testing"
func TestSum(t *testing.T) {
if got := Sum(1, 2, 3); got != 6 {
t.Errorf("Sum(1, 2, 3) = %d, want 6", got)
}
if got := Sum(); got != 0 {
t.Errorf("Sum() = %d, want 0", got)
}
}
func TestAverage(t *testing.T) {
if got := Average(1, 2, 4); got != 7.0/3.0 {
t.Errorf("Average(1, 2, 4) = %v, want 2.3333", got)
}
}
go test -v ./...
=== RUN TestSum
--- PASS: TestSum (0.00s)
=== RUN TestAverage
--- PASS: TestAverage (0.00s)
PASS
ok example.com/ci 0.007s
The summary line names the module path rather than the directory, because that is the package the toolchain built. ./... walks every package below the module root, so a project with a library and a command tests both from the same command; the job does not need to know the layout.
A failing test
A job that never fails proves nothing, so the next run has a wrong expectation on purpose: the test asks for 7 and the function returns 6. The runner reports the file, the line, the call, the value and the expectation, and the package summary changes from ok to FAIL with a non-zero exit status.
package main
import "testing"
func TestSum(t *testing.T) {
if got := Sum(1, 2, 3); got != 7 {
t.Errorf("Sum(1, 2, 3) = %d, want 7", got)
}
}
go test -v -run TestSum . ; echo "exit status: $?"
=== RUN TestSum
sum_test.go:7: Sum(1, 2, 3) = 6, want 7
--- FAIL: TestSum (0.00s)
FAIL
FAIL example.com/ci 0.006s
FAIL
exit status: 1
The job reads the exit status, not the text: status 1 fails the step and the run. The message is for the person who opens the log, and it is worth writing it so that the line alone says what was expected.
The workflow file
GitHub Actions reads a YAML file under .github/workflows/. The steps below install the Go version named in go.mod, cache the module downloads, and run the three checks of the first section plus the tests with the race detector. The file is configuration, not a Go program: it was written for this lesson and is not run in this container, which has no CI runner.
name: ci
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
cache: true
- run: test -z "$(gofmt -l .)"
- run: go vet ./...
- run: go test -race ./...
- run: go build ./...
go-version-file keeps the runner and the module on one version without a second place to edit, and cache: true stores the module cache between runs, which is the difference between a job that downloads the dependencies every time and one that does not. The step order is deliberate: formatting is cheapest, vet is next, the tests take the longest, and the build comes last so a green run has produced the artifact the next job would deploy.
Two habits keep the job honest. Pin the action versions, as @v4 does, because a moving tag can change what the job runs without a commit. And run the same commands locally before the push: a job that is the first place a check ever runs is a job that fails for reasons the developer could have seen in a second.
Exercises
- Add a package under internal/ and run go test ./... again. How many summary lines does the output have, and why?
- Run gofmt -l . on a file with a stray space and read the exit status. What does the check in the workflow test, and what would it miss?
- Break a format string in main and run go vet ./.... Which step of the job fails first, and what does the log line name?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which three commands form the local check loop of a small Go package?
Answer
gofmt, go vet and go test
Formatting, static analysis and the tests are the checks a job repeats.
-
Why is gofmt -l not enough on its own?
Answer
It prints the files it would change and exits 0 either way
The job tests that its output is empty.
-
What does go test -v ./... print for a passing package?
Answer
The test names and a final ok line with the time
Verbose mode lists each test; the package summary is the ok line.
-
What does a failed test make go test return?
Answer
Exit status 1
The non-zero status is what fails the CI step.
-
What is the advantage of ./... in the test command?
Answer
It tests every package below the module root
The job does not need to know the package layout.
-
What does cache: true in setup-go store?
Answer
The module downloads between runs
The module cache is the slow part of a fresh job.
-
Why does go-version-file point at go.mod?
Answer
It keeps the runner on the version the module declares
One version, one place to edit.
-
Why pin an action to @v4 rather than a branch?
Answer
Because a moving branch can change what the job runs without a commit
A pinned release is a stable build input.
-
In which order do the steps of the workflow above run?
Answer
Formatting, vet, tests with the race detector, build
The cheapest checks fail first; the build comes last.
-
What does the lesson say about the workflow file?
Answer
It is configuration written for the lesson and not run here
The container has no CI runner, and the page does not invent its output.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev