golangBuild

This step will execute a golang build.

Description

This step will build a golang project. It will also execute golang-based tests using gotestsum and with that allows for reporting test results and test coverage.

Besides execution of the default tests the step allows for running an additional integration test run using -tags=integration using pattern ./...

If the build is successful the resulting artifact can be uploaded to e.g. a binary repository automatically.

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

JenkinsCommand Line

library('piper-lib-os')

golangBuild script: this

piper golangBuild

Outputs

Output type	Details
commonPipelineEnvironment	custom/buildSettingsInfo custom/artifacts

Parameters

Overview - Step

Name	Mandatory	Additional information
script	(yes)	reference to Jenkins main pipeline script
artifactVersion	no
buildFlags	no
buildSettingsInfo	no
cgoEnabled	no
coverageFormat	no
createBOM	no
customTlsCertificateLinks	no
excludeGeneratedFromCoverage	no
failOnLintingError	no
golangciLintUrl	no
ldflagsTemplate	no
output	no
packages	no
privateModules	no
privateModulesGitToken	no	pass via ENV, Vault or Jenkins credentials (golangPrivateModulesGitTokenCredentialsId)
publish	no
reportCoverage	no
runIntegrationTests	no
runLint	no
runTests	no
targetArchitectures	no
targetRepositoryPassword	no	pass via ENV or Jenkins credentials
targetRepositoryURL	no
targetRepositoryUser	no	pass via ENV or Jenkins credentials
testOptions	no
testResultFormat	no
verbose	no	activates debug output

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name	Mandatory	Additional information
containerCommand	no
containerShell	no
dockerEnvVars	no
dockerImage	no
dockerName	no
dockerOptions	no
dockerPullImage	no
dockerVolumeBind	no
dockerWorkspace	no

Details

artifactVersion

Version of the artifact to be built.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_artifactVersion (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: artifactVersion

buildFlags

Defines list of build flags to be used.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_buildFlags (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

buildSettingsInfo

build settings info is typically filled by the step automatically to create information about the build settings that were used during the maven build . This information is typically used for compliance related processes.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_buildSettingsInfo (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/buildSettingsInfo

cgoEnabled

If active: enables the creation of Go packages that call C code.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

containerCommand

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

containerShell

Jenkins-specific: Used for proper environment setup.

Allows to specify the shell to be executed for container with containerName.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

coverageFormat

Defines the format of the coverage repository.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	html
Possible values	- cobertura - html
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

createBOM

Creates the bill of materials (BOM) using CycloneDX plugin. It requires Go 1.17 or newer.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

customTlsCertificateLinks

List of download links to custom TLS certificates. This is required to ensure trusted connections to instances with repositories (like nexus) when publish flag is set to true.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_customTlsCertificateLinks (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerEnvVars

Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].

back to overview

Scope	Details
Aliases	-
Type	map[string]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerImage

Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	golang:1
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerName

Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	golang
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerOptions

Docker options to be set when starting the container.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	[{-u 0}]
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerPullImage

Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerVolumeBind

Jenkins-specific: Used for proper environment setup.

Volumes that should be mounted into the docker container.

back to overview

Scope	Details
Aliases	-
Type	map[string]string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerWorkspace

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

excludeGeneratedFromCoverage

Defines if generated files should be excluded, according to https://golang.org/s/generatedcode.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

failOnLintingError

Defines if step will return an error in case linting runs into a problem

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

golangciLintUrl

Specifies the download url of the Golangci-Lint Linux amd64 tar binary file. This can be found at https://github.com/golangci/golangci-lint/releases.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	https://github.com/golangci/golangci-lint/releases/download/v1.51.2/golangci-lint-1.51.2-linux-amd64.tar.gz
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☐ stages
Resource references	none

ldflagsTemplate

The template allows using commonPipelineEnvironment parameters in the form .CPE["<paramName>"]

Examples

* `-X github.com/SAP/jenkins-library/pkg/log.Version={{index .CPE "artifactVersion"}}`.
* `-X github.com/SAP/jenkins-library/pkg/log.LibraryRepository={{index .CPE "custom/repositoryId"}}`

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_ldflagsTemplate (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

output

Defines the build result or output directory as per go build documentation.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_output (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

packages

List of packages to be build as per go build documentation.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_packages (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

privateModules

Tells go which modules shall be considered to be private (by setting GOPRIVATE).

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_privateModules (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

privateModulesGitToken

GitHub personal access token as per https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_privateModulesGitToken (if set)
Secret	yes
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: golangPrivateModulesGitTokenCredentialsId   reference to: password Vault resource:   name: golangPrivateModulesGitTokenVaultSecret   default value: golang Vault paths: $(vaultPath)/golang $(vaultBasePath)/$(vaultPipelineName)/golang $(vaultBasePath)/GROUP-SECRETS/golang

publish

Configures the build to publish artifacts to a repository.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

reportCoverage

Defines if a coverage report should be created.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

runIntegrationTests

Activates execution of a second test run using tag integration.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

runLint

Configures the build to run linters with golangci-lint.

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

runTests

Activates execution of tests using gotestsum. Tag Go unit tests with 'unit' build tag to exclude them using --runTests=false

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	true
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

script

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope	Details
Aliases	-
Type	Jenkins Script
Mandatory	yes
Default
Secret	no
Configuration scope	☐ parameter ☐ general ☐ steps ☐ stages
Resource references	none

targetArchitectures

Defines the target architectures for which the build should run using OS and architecture separated by a comma.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	linux,amd64
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

targetRepositoryPassword

Password for the target repository where the compiled binaries shall be uploaded - typically provided by the CI/CD environment.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_targetRepositoryPassword (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/rawRepositoryPassword commonPipelineEnvironment:   reference to: custom/repositoryPassword

targetRepositoryURL

URL of the target repository where the compiled binaries shall be uploaded - typically provided by the CI/CD environment.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_targetRepositoryURL (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/rawRepositoryURL commonPipelineEnvironment:   reference to: custom/repositoryUrl

targetRepositoryUser

Username for the target repository where the compiled binaries shall be uploaded - typically provided by the CI/CD environment.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_targetRepositoryUser (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: custom/rawRepositoryUsername commonPipelineEnvironment:   reference to: custom/repositoryUsername

testOptions

Options to pass to test as per go test documentation (comprises e.g. flags, packages).

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_testOptions (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

testResultFormat

Defines the output format of the test results.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	junit
Possible values	- junit - standard
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

verbose

verbose output

back to overview

Scope	Details
Aliases	-
Type	bool
Mandatory	no
Default	false
Possible values	- true - false
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

golangPrivateModulesGitTokenCredentialsId

Jenkins 'Username with password' credentials ID containing username/password for http access to your git repos where your go private modules are stored.

back to overview

Scope	Details
Aliases	-
Type	string
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages