GitLab CI template for Go

This project implements a GitLab CI/CD template to build, test and analyse your Go projects.

Usage

In order to include this template in your project, add the following to your gitlab-ci.yml:

include:
  - project: 'to-be-continuous/golang'
    ref: '4.1.1'
    file: '/templates/gitlab-ci-golang.yml'

Global configuration

The Go template uses some global configuration used throughout all jobs.

Jobs

build & test jobs

You can specify if you want the template to build an application or modules with the GO_BUILD_MODE variable. It may have the following values:

• application will make the build output the binaries (use -o build option, won't work if there is no main.go file)
• modules won't output the binaries (no use of the -o option)
• auto the template will rely on the presence of a main.go file to detect if it should output the binaries.

The build target platform is the one defined by the docker image but it can be overriden using the GO_TARGET_OS and GO_TARGET_ARCH variables.

variables:
  GO_TARGET_OS: "windows"
  GO_TARGET_ARCH: "amd64"

Build and tests can be done in separate jobs. If GO_TEST_IMAGE is not set (default), the go-build-test job will run build and tests at once. If GO_TEST_IMAGE is set, separate go-build and go-test jobs will be run in the build phase in parallel.

Separating build and test jobs can be useful to use different images (and hence different tools) or if you want to build muli-platform binaries.

Here is a .gitlab-ci.yml example that triggers a build on 3 target platforms using the parallel matrix jobs pattern:

variables:
  GO_IMAGE: "registry.hub.docker.com/library/golang:1.17-buster"
  GO_TEST_IMAGE: "registry.hub.docker.com/library/golang:1.17-buster"

go-build:
  parallel:
    matrix:
      - GO_TARGET_OS: "windows"
        GO_TARGET_ARCH: "amd64"
      - GO_TARGET_OS: "linux"
        GO_TARGET_ARCH: "amd64"
      - GO_TARGET_OS: "linux"
        GO_TARGET_ARCH: "arm"

These jobs use the following variable:

In addition to a textual report in the console, the test jobs produce the following reports, kept for one day:

go-ci-lint job

This job enables a manual GolangCI-Lint analysis.

It is bound to the build stage, and uses the following variables:

In addition to a textual report in the console, this job produces the following reports, kept for one day:

go-mod-outdated job

This job enables a manual Go-mod-outdated analysis.

It is bound to the test stage, and uses the following variables:

Checking outdated modules can be a long operation and therefore the job is configured to be ran manually by default (overridable).

SonarQube analysis

If you're using the SonarQube template to analyse your Go code, here is a sample sonar-project.properties file:

# see: https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/test-execution-parameters/#go
# set your source directory(ies) here (relative to the sonar-project.properties file)
sonar.sources=.
# exclude unwanted directories and files from being analysed
sonar.exclusions=bin/**,**/*_test.go,**/vendor/**

# set your tests directory(ies) here (relative to the sonar-project.properties file)
sonar.tests=.
sonar.test.inclusions=**/*_test.go
sonar.test.exclusions=**/vendor/**

# tests report: JSON native format
sonar.go.tests.reportPaths=reports/go-test.native.json
# coverage report: native format
sonar.go.coverage.reportPaths=reports/go-coverage.native.out
# golanci-lint: checkstyle report (if enabled)
sonar.go.golangci-lint.reportPaths=reports/go-ci-lint.checkstyle.xml

More info:

• Go language support
• test coverage & execution parameters
• third-party issues

⚠️ an unsolved issue may prevent SonarQube Go plugin from importing your test reports.

go-sbom job

This job generates a SBOM file listing installed packages using @cyclonedx/cyclonedx-gomod.

It is bound to the test stage, and uses the following variables: