githubSetCommitStatus¶
Set a status of a certain commit.
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 |
---|---|---|
commitId | yes | |
context | yes | |
owner | yes | |
repository | yes | |
script | (yes) | reference to Jenkins main pipeline script |
status | yes | |
token | (yes) | pass via ENV, Vault or Jenkins credentials (githubTokenCredentialsId ) |
apiUrl | no | |
description | no | |
targetUrl | 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¶
apiUrl¶
Set the GitHub API URL.
Scope | Details |
---|---|
Aliases | githubApiUrl |
Type | string |
Mandatory | no |
Default | https://api.github.com |
Secret | no |
Configuration scope |
|
Resource references | none |
commitId¶
The commitId for which the status should be set.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_commitId (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: git/commitId |
context¶
Label for the status which will for example show up in a pull request.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_context (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
description¶
Short description of the status.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_description (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
owner¶
Name of the GitHub organization.
Scope | Details |
---|---|
Aliases | githubOrg |
Type | string |
Mandatory | yes |
Default | $PIPER_owner (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: github/owner |
repository¶
Name of the GitHub repository.
Scope | Details |
---|---|
Aliases | githubRepo |
Type | string |
Mandatory | yes |
Default | $PIPER_repository (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: github/repository |
script¶
Jenkins-specific: Used for proper environment setup.
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
status¶
Status which should be set on the commitId.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_status (if set) |
Possible values | - failure - pending - success |
Secret | no |
Configuration scope |
|
Resource references | none |
targetUrl¶
Target URL to associate the status with.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_targetUrl (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - githubToken - access_token |
Type | string |
Mandatory | yes |
Default | $PIPER_token (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: githubTokenCredentialsId Vault resource: name: githubVaultSecretName default value: github Vault paths:
|
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
githubTokenCredentialsId¶
Jenkins-specific: Used for proper environment setup. See using credentials for details.
Jenkins 'Secret text' credentials ID containing token to authenticate to GitHub.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|
Description¶
This step allows you to set a status for a certain commit. Details can be found here: https://developer.github.com/v3/repos/statuses/.
Typically, following information is set:
- state (pending, failure, success)
- context
- target URL (link to details)
It can for example be used to create additional check indicators for a pull request which can be evaluated and also be enforced by GitHub configuration.
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.
library('piper-lib-os')
githubSetCommitStatus script: this
piper githubSetCommitStatus