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

  1. Add a package under internal/ and run go test ./... again. How many summary lines does the output have, and why?
  2. 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?
  3. 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.

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

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

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

  4. What does a failed test make go test return?

    Answer

    Exit status 1

    The non-zero status is what fails the CI step.

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

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

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

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

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

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