GitHub Actions includes CI/CD for free for Open Source repositories. This document contains information on making it work well for Go. See them in action:
$ cat .github/workflows/test.yml
on: [push, pull_request]
name: Test
jobs:
test:
strategy:
matrix:
go-version: [1.21.x, 1.22.x]
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-go@v5
with:
go-version: ${{ matrix.go-version }}
- uses: actions/checkout@v4
- run: go test ./...
Each workflow file has a number of jobs, which get run on
specified events,
and run concurrently with each other. You can have workflow status badges.
Each job
runs on a configuration matrix
. For example, we can test two major
Go versions on three operating systems.
Each job has a number of steps
, such as installing Go, or checking out the
repository's code.
Note that name
fields are optional.
They can be set up via env
for an entire
workflow,
a job, or for each step:
env:
GOPROXY: "https://proxy.company.com"
jobs:
[...]
You can use environment files
to set environment variables or add an element to $PATH
. For example:
steps:
- name: Set env vars
run: |
echo "CGO_ENABLED=0" >> $GITHUB_ENV
echo "${HOME}/goroot/bin" >> $GITHUB_PATH
Note that these take effect for future steps in the job.
Since v4, actions/setup-go caches GOCACHE
and GOMODCACHE
automatically, using go.sum
as the cache key.
You can turn that off via cache: false
, and then you may also use your own
custom caching, for example to only keep GOMODCACHE
:
- uses: actions/cache@v3
with:
path: ~/go/pkg/mod
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
restore-keys: |
${{ runner.os }}-go-
See this guide for more details.
You can use if
conditionals, using their custom expression
language:
- if: github.event_name == 'push' && matrix.os == 'ubuntu-latest'
run: go run ./endtoend
You can include extra matrix jobs, and you can exclude specific matrix jobs.
- name: Series of commands
run: |
go test ./...
go test -race ./...
The biggest difference is the UI; workflow results are shown separately. Grouping jobs in workflows can also be useful if one wants to customize the workflow triggers, or to set up dependencies via needs.
Follow these steps
to set up the secret in the repo's settings. After adding a secret like
FOO_SECRET
, use it on a step as follows:
- run: some-command
env:
FOO_SECRET: ${{ secrets.FOO_SECRET }}
It's possible to install modules from private GitHub repositories without using your own proxy. You'll need to add a personal access token as a secret environment variable, as well as configure GOPRIVATE. You can also directly used the token provided by GitHub in the workflow. You can define anything as username in the URL, it is not taken into account by GitHub.
- name: Configure git for private modules
env:
TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
run: git config --global url."https://user:${TOKEN}@github.com".insteadOf "https://github.com"
env:
GOPRIVATE: "*.company.com"
jobs:
[...]
Use sudo apt
, making sure to only run the step on Linux:
- if: matrix.os == 'ubuntu-latest'
run: sudo apt update && sudo apt install -y --no-install-recommends mypackage
Declare GOPATH
and clone inside of it:
jobs:
test-gopath:
env:
GOPATH: ${{ github.workspace }}
GO111MODULE: off
defaults:
run:
working-directory: ${{ env.GOPATH }}/src/github.com/${{ github.repository }}
steps:
- uses: actions/checkout@v3
with:
path: ${{ env.GOPATH }}/src/github.com/${{ github.repository }}
-
Concepts, rate limits, etc: https://docs.github.com/en/actions/learn-github-actions
-
Syntax and fields reference: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
-
GitHub-hosted runners: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners
git config core.autocrlf
defaults to true, so be careful about CRLF endings in
your plaintext testdata
files on Windows. To work around this, set up the
following .gitattributes
:
* -text