githubPublishRelease¶

Publish a release in GitHub

Prerequisites¶

You need to create a personal access token within GitHub and add this to the Jenkins credentials store.

Please see GitHub documentation for details about creating the personal access token.

Parameters¶

Overview - Step¶

Name	Mandatory	Additional information
owner	yes
repository	yes
script	(yes)	reference to Jenkins main pipeline script
token	(yes)	pass via ENV, Vault or Jenkins credentials (`githubTokenCredentialsId`)
version	yes
addClosedIssues	no
addDeltaToLastRelease	no
apiUrl	no
assetPath	no
assetPathList	no
commitish	no
excludeLabels	no
labels	no
preRelease	no
releaseBodyHeader	no
serverUrl	no
tagPrefix	no
uploadUrl	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

Details¶

addClosedIssues¶

If set to true, closed issues and merged pull-requests since the last release will added below the releaseBodyHeader

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

addDeltaToLastRelease¶

If set to true, a link will be added to the release information that brings up all commits since the last release.

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

apiUrl¶

Set the GitHub API url.

back to overview

Scope	Details
Aliases	`githubApiUrl`
Type	`string`
Mandatory	no
Default	`https://api.github.com`
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

assetPath¶

Path to a release asset which should be uploaded to the list of release assets.

back to overview

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

assetPathList¶

List of paths to a release asset which should be uploaded to the list of release assets.

back to overview

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

commitish¶

Target git commitish for the release

back to overview

Scope	Details
Aliases	-
Type	`string`
Mandatory	no
Default	`master`
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment: reference to: `git/headCommitId`

excludeLabels¶

Allows to exclude issues with dedicated list of labels.

back to overview

Scope	Details
Aliases	-
Type	`[]string`
Mandatory	no
Default	- `duplicate` - `invalid` - `question` - `wontfix`
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

labels¶

Labels to include in issue search.

back to overview

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

owner¶

Name of the GitHub organization.

back to overview

Scope	Details
Aliases	`githubOrg`
Type	`string`
Mandatory	yes
Default	`$PIPER_owner` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment: reference to: `github/owner`

preRelease¶

If set to true the release will be marked as Pre-release.

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

releaseBodyHeader¶

Content which will appear for the release.

back to overview

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

repository¶

Name of the GitHub repository.

back to overview

Scope	Details
Aliases	`githubRepo`
Type	`string`
Mandatory	yes
Default	`$PIPER_repository` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment: reference to: `github/repository`

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

serverUrl¶

GitHub server url for end-user access.

back to overview

Scope	Details
Aliases	`githubServerUrl`
Type	`string`
Mandatory	no
Default	`https://github.com`
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

tagPrefix¶

Defines a prefix to be added to the tag.

back to overview

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

token¶

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	- `githubToken` - `access_token`
Type	`string`
Mandatory	yes
Default	`$PIPER_token` (if set)
Secret	yes
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	Jenkins credential id: id: `githubTokenCredentialsId` Vault resource: name: `githubVaultSecretName` default value: `github` Vault paths: `$(vaultPath)/github` `$(vaultBasePath)/$(vaultPipelineName)/github` `$(vaultBasePath)/GROUP-SECRETS/github`

uploadUrl¶

Set the GitHub API url.

back to overview

Scope	Details
Aliases	`githubUploadUrl`
Type	`string`
Mandatory	no
Default	`https://uploads.github.com`
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

version¶

Define the version number which will be written as tag as well as release name.

back to overview

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

githubTokenCredentialsId¶

Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.

back to overview

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

Description¶

This step creates a tag in your GitHub repository together with a release. The release can be filled with text plus additional information like:

Closed pull request since last release
Closed issues since last release
Link to delta information showing all commits since last release

The result looks like

Example release

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')

githubPublishRelease script: this

piper githubPublishRelease

Example¶

Usage of pipeline step:

githubPublishRelease script: this, releaseBodyHeader: "**This is the latest success!**<br />"