Skip to content

githubCheckBranchProtection

Check branch protection of a GitHub branch

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) Jenkins only reference to Jenkins main pipeline script
token (yes) Vault Secret pass via ENV, Vault or Jenkins credentials (githubTokenCredentialsId)
apiUrl no
branch no
requireEnforceAdmins no
requiredApprovingReviewCount no
requiredChecks 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.

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

branch

The name of the branch for which the protection settings should be checked.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default master
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

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

requireEnforceAdmins

Check if 'Include Administrators' option is set in the GitHub repository configuration.

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

requiredApprovingReviewCount

Check if 'Require pull request reviews before merging' option is set with at least the defined number of reviewers in the GitHub repository configuration.

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 0
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

requiredChecks

List of checks which have to be set to 'required' in the GitHub repository configuration.

back to overview

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

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.

back to overview

Scope Details
Aliases -
Type Jenkins Script
Mandatory yes
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

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

githubTokenCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

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 allows you to check if certain branch protection rules are fulfilled.

It can for example be used to verify if certain status checks are mandatory. This can be helpful to decide if a certain check needs to be performed again after merging a pull request.

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

githubCheckBranchProtection script: this
piper githubCheckBranchProtection