Repository files navigation

GitHub Actions includes CI/CD for freefor Open Source repositories. This document contains information on making itwork well forGo. See theminaction:

$ cat .github/workflows/test.ymlon:[push, pull_request]name:Testjobs:test:strategy:matrix:go-version:[1.23.x, 1.24.x]os:[ubuntu-latest, macos-latest, windows-latest]runs-on:${{ matrix.os }}steps:    -uses:actions/checkout@v4    -uses:actions/setup-go@v5with:go-version:${{ matrix.go-version }}    -run:go test ./...

Each workflow file has a number of jobs, which get runon specified events,and run concurrently with each other. You can have workflowstatus badges.

Eachjob runs on a configurationmatrix. For example, we can test two majorGo versions on three operating systems.

Each job has a number ofsteps, such as installing Go, or checking out therepository's code.

Note thatname fields are optional.

They can be set up viaenv for anentireworkflow,a job, or for each step:

env:GOPROXY:"https://proxy.company.com"jobs:[...]

You can useenvironment filesto set environment variables or add an element to$PATH. For example:

steps:-name:Set env varsrun:|      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 cachesGOCACHEandGOMODCACHE automatically, usinggo.sum as the cache key.You can turn that off viacache: false, and then you may also use your owncustom caching, for example to only keepGOMODCACHE:

-uses:actions/cache@v3with:path:~/go/pkg/modkey:${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}restore-keys:|      ${{ runner.os }}-go-

Seethis guidefor more details.

You can useif conditionals, using theircustom expressionlanguage:

-if:github.event_name == 'push' && matrix.os == 'ubuntu-latest'run:go run ./endtoend

You caninclude extra matrixjobs,and you canexclude specific matrixjobs.

-name:Series of commandsrun:|    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 theworkflow triggers, or to set up dependencies vianeeds.

Followthese stepsto set up the secret in the repo's settings. After adding a secret likeFOO_SECRET, use it on a step as follows:

-run:some-commandenv:FOO_SECRET:${{ secrets.FOO_SECRET }}

It's possible to install modules from private GitHub repositories without usingyour own proxy. You'll need to add apersonal access token as a secretenvironment variable, as well as configureGOPRIVATE.You can also directly used the tokenprovided by GitHubin the workflow.You can define anything as username in the URL, it is not taken into account by GitHub.

-name:Configure git for private modulesenv:TOKEN:${{ secrets.PERSONAL_ACCESS_TOKEN }}run:git config --global url."https://user:${TOKEN}@github.com".insteadOf "https://github.com"

env:GOPRIVATE:"*.company.com"jobs:[...]

Usesudo 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

• Concepts, rate limits, etc:https://docs.github.com/en/actions/writing-workflows

• Syntax and fields reference:https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions

• GitHub-hosted runners:https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners

• actions/checkout#135

git config core.autocrlf defaults to true, so be careful about CRLF endings inyour plaintexttestdata files on Windows. To work around this, set up thefollowing.gitattributes:

*-text