IntroductionPipeline termsPipeline project typesCloudBees Pipeline benefits
IntroductionUsing Pipeline development utilitiesDetermining plugin compatibilityPipeline best practices
IntroductionPrerequisitesCreating your first PipelineCreating Pipelines in SCMCreating Pipelines in Web UIUsing Pipeline as Code
IntroductionConfig Adv ScriptedConfig Build StageConfig Deploy StageConfig Optional Step ArgsConfig Test StageCreating JenkinsfileCustomizing ParametersHandling FailuresString InterpolationUsing Multiple AgentsWorking With The Env
IntroductionManaging artifactsTracing artifactsTriggering jobs with a simple webhookRestoring filesVisualizing PipelineInserting checkpointsSecuring PipelinesConfiguring Pipelines with user-scoped credentialsUsing Pipeline PoliciesSpecifying a matrix of one or more dimensionsConverting a Freestyle project to a Declarative Pipeline
IntroductionRestarting aborted buildsLong-running buildsSkip next buildConsolidated Build View pluginCloudBees Quiet Start pluginCloudBees Template pluginCloudBees Git Validated Merge plugin
IntroductionTrigger a job with a notification event using Cross Team CollaborationEnable external notification events with external HTTP endpointsCluster-wide copy artifactsCluster-wide job triggers
IntroductionSetting up a Pipeline Template CatalogDefining Pipeline Template CatalogsSetting Up A Pipeline TemplateUsing parameters in template.yamlManaging multibranch Pipeline options in template.yamlManaging Pipeline Template Catalogs in bulkExample full Maven/Java app Jenkinsfile
IntroductionUsing Declarative Pipeline syntaxUsing Scripted Pipeline syntax
IntroductionBranch SourceBitbucketGitBranch Property StrategyExamples
CloudBees Docker Build and Publish pluginCloudBees Docker TraceabilityDocker Pipeline pluginCloudBees Docker Hub/Registry Notification plugin
IntroductionExplaining $JENKINS_HOMEBest practices for backup and restoreBacking up manuallyRestoring manuallyRestoring credentialsUsing the CloudBees Backup PluginScheduling your backups in the CloudBees Backup PluginRestoring from CloudBees Backup PluginUsing cluster operations to run backups
IntroductionGetting the CLI toolUsing the CLI toolExamples of usageConfiguring multiple client controllersConfiguring an alias for the Jenkins CLI toolConfiguring the Jenkins CLI tool to work with non-TrustStore SSL certificatesCasC bundle management on operations center
CloudBees Inactive Items Plugin
Jenkins Health Advisor by CloudBees
CloudBees Pull Request Builder for GitHub plugin
Counting and monitoring user licenses with the CloudBees User Activity Monitoring plugin
Support policies

GitHub

8 minute read
The starting point is the BranchSource object, so configurations always start with branchSource:.
For more information on how to configure various options related to Multibranch Pipelines via YAML syntax, see Mutibranch Pipeline Template yaml syntax guide.
Table 1. GitHub parameters
Parameter Type Description

repoOwner

String

Specify the name of the GitHub Organization or GitHub User Account.

repository

String

The repository to scan.

apiUri (optional)

String

The server to connect to. The list of servers is configured in the Manage Jenkins » Configure Jenkins › GitHub Enterprise Servers page.

buildForkPRHead (optional)

boolean

buildForkPRMerge (optional)

boolean

buildOriginBranch (optional)

boolean

buildOriginBranchWithPR (optional)

boolean

buildOriginPRHead (optional)

boolean

buildOriginPRMerge (optional)

boolean

credentialsId (optional)

String

Credentials used to scan branches and pull requests, check out sources, and mark commit statuses.

Only username with password credentials are supported.

Existing credentials of other kinds will be filtered out.

This is because Jenkins uses the GitHub API, which does not support other ways of authentication.

If none is given, only the public repositories will be scanned, and commit status will not be set on GitHub.

If your organization contains private repositories, then you need to specify a credential from a user who has access to those repositories. This is done by creating a username with password credential where the password is GitHub personal access tokens. The necessary scope is repo.

excludes (optional)

String

id (optional)

String

includes (optional)

String

traits

List of Nested Choice of SCMSourceTrait objects

The behaviors control what is discovered from the GitHub repository.

SCMSourceTrait objects

  • $class: 'AuthorInChangelogTrait'

    Use Commit author in changelog.

  • $class: 'CheckoutOptionTrait'

    Advanced checkout behaviors.

    Table 2. CheckoutOptionTrait parameters
    Parameter Type Description

    extension

    Nested CheckoutOption object

  • $class: 'CleanAfterCheckoutTrait'

    Clean after checkout.

  • $class: 'CleanBeforeCheckoutTrait'

    Clean before checkout.

  • $class: 'CloneOptionTrait'

    Advanced clone behaviors.

    Table 3. CloneOptionTrait parameters
    Parameter Type Description

    extension

    Nested CloneOption object

  • $class: 'GitLFSPullTrait'

    Git LFS pull after checkout.

  • $class: 'GitToolSCMSourceTrait'

    Table 4. GitToolSCMSourceTrait parameters
    Parameter Type Description

    gitTool

    String

  • $class: 'LocalBranchTrait'

    Checkout to matching local branches.

  • $class: 'PruneStaleBranchTrait'

    Prune stale remote-tracking branches.

  • $class: 'RefSpecsSCMSourceTrait'

    Specify ref specs.

    Table 5. RefSpecsSCMSourceTrait parameters
    Parameter Type Description

    templates

    List of Nested RefSpecTemplate object

  • headRegexFilter

    Filter by name (with regular expression)

    Table 6. headRegexFilter parameters
    Parameter Type Description

    regex

    String

    A Java regular expression to restrict the names. Names that do not match the supplied regular expression will be ignored.

    This filter will be applied to all branch like things, including change requests.

  • $class: 'RemoteNameSCMSourceTrait'

    Configure remote name.

    Table 7. RemoteNameSCMSourceTrait parameters
    Parameter Type Description

    remoteName

    String

  • $class: 'SparseCheckoutPathsTrait'

    Sparse Checkout paths.

    Table 8. SparseCheckoutPathsTrait parameters
    Parameter Type Description

    extension

    Nested SparseCheckoutPaths object

  • $class: 'SubmoduleOptionTrait'

    Advanced sub-modules behaviors

    Table 9. SubmoduleOptionTrait parameters
    Parameter Type Description

    extension

    Nested SubmoduleOption object

  • $class: 'UserIdentityTrait'

    Custom user/e-mail address.

    Table 10. UserIdentityTrait parameters
    Parameter Type Description

    extension

    Nested UserIdentity object

  • headWildcardFilter

    Filter by name (with wildcards)

    Table 11. headWildcardFilter parameters
    Parameter Type Description

    includes

    String

    Space-separated list of name patterns to consider. You may use as a wildcard; for example: master release.

    This filter will be applied to all branch like things, including change requests.

    excludes

    String

    Space-separated list of name patterns to ignore even if matched by the includes list. For example: release alpha-* beta-*.

    This filter will be applied to all branch like things, including change requests.

  • $class: 'WipeWorkspaceTrait'

    Wipe out repository data and force clone.

  • gitHubBranchDiscovery

    Discovers branches on the repository.

    Table 12. gitHubBranchDiscovery parameters
    Parameter Type Description

    strategyId

    int

    Determines which branches are discovered.

    • Exclude branches that are also filed as PRs

      If you are discovering origin pull requests, you may not want to also build the source branches for those pull requests.

    • Only branches that are also filed as PRs

      Similar to discovering origin pull requests, but discovers the branch rather than the pull request. This means env.GIT_BRANCH will be set to the branch name rather than PR-#. Also, status notifications for these builds will only be applied to the commit and not to the pull request.

    • All branches

      Ignores whether the branch is also filed as a pull request and instead discovers all branches on the origin repository.

  • gitHubForkDiscovery

    Discovers pull requests where the origin repository is a fork of the target repository.

    Table 13. gitHubForkDiscovery parameters
    Parameter Type Description

    strategyId

    int

    Determines how pull requests are discovered.

    • Merging the pull request with the current target branch revision

      Discover each pull request once with the discovered revision corresponding to the result of merging with the current revision of the target branch.

    • The current pull request revision

      Discover each pull request once with the discovered revision corresponding to the pull request head revision without merging.

    • Both the current pull request revision and the pull request merged with the current target branch revision

      Discover each pull request twice. The first discovered revision corresponds to the result of merging with the current revision of the target branch in each scan. The second parallel discovered revision corresponds to the pull request head revision without merging.

    trust

    Nested Choice of SCMHeadAuthority objects

    One of the great powers of pull requests is that anyone with read access to a repository can fork it, commit some changes to their fork and then create a pull request against the original repository with their changes. There are some files stored in source control that are important.

    For example, a Jenkinsfile may contain configuration details to sandbox pull requests in order to mitigate against malicious pull requests. In order to protect against a malicious pull request itself modifying the Jenkinsfile to remove the protections, you can define the trust policy for pull requests from forks. Other plugins can extend the available trust policies.

  • gitHubPullRequestDiscovery

    Discovers pull requests where the origin repository is the same as the target repository.

    Table 14. gitHubPullRequestDiscovery parameters
    Parameter Type Description

    strategyId

    int

    Determines how pull requests are discovered.

    • Merging the pull request with the current target branch revision

      Discover each pull request once with the discovered revision corresponding to the result of merging with the current revision of the target branch.

    • The current pull request revision

      Discover each pull request once with the discovered revision corresponding to the pull request head revision without merging.

    • Both the current pull request revision and the pull request merged with the current target branch revision

      Discover each pull request twice. The first discovered revision corresponds to the result of merging with the current revision of the target branch in each scan. The second parallel discovered revision corresponds to the pull request head revision without merging.

  • gitHubSshCheckout

    By default the discovered branches/pull requests will all use the same username/password credentials that were used for discovery when checking out sources.

    This means that the checkout will be using the https:// protocol for the Git repository.

This behavior allows you to select the SSH private key to be used for checking out sources, which will consequently force the checkout to use the ssh://` protocol.

+

.gitHubSshCheckout parameters

Parameter

Type

Description

credentialsId

String

Credentials used to check out sources. Must be a SSH key based credential.

  • gitHubTagDiscovery

    Discovers tags on the repository

SCMHeadAuthority objects

  • $class: 'TrustNobody'

    Pull requests from forks will all be treated as untrusted. This means that where Jenkins requires a trusted file (for example, Jenkinsfile) the contents of that file will be retrieved from the target branch on the origin repository and not from the pull request branch on the fork repository.

  • $class: 'TrustContributors'

    Pull requests from collaborators to the origin repository will be treated as trusted, all other pull requests from fork repositories will be treated as untrusted. If credentials used by Jenkins for scanning the repository does not have permission to query the list of contributors to the origin repository then only the origin account will be treated as trusted - in other words, this will fall back to Nobody.

All collaborators are trusted, even if they are only members of a team with read permission.

  • $class: 'TrustEveryone'

    All pull requests from forks will be treated as trusted.

This option can be dangerous if used on a public repository hosted on GitHub.

  • $class: 'TrustPermission'

    Pull requests forks will be treated as trusted if and only if the fork owner has either Admin or Write permissions on the origin repository. This is the recommended policy. This strategy requires the Review a user’s permission level API, as a result on GitHub Enterprise Server versions before 2.12 this is the same as trusting Nobody.

Nested objects

CheckoutOption object

Advanced checkout behaviors.

Table 15. CheckoutOption object parameters
Parameter Type Description

timeout

int

Specify a timeout (in minutes) for checkout.

This option overrides the default timeout of 10 minutes.

You can change the global git timeout via the property org.jenkinsci.plugins.gitclient.Git.timeOut.

Property should be set on both controller and agent to have effect.

CloneOption object

Advanced clone behaviors.

Table 16. CloneOption object parameters
Parameter Type Description

shallow

boolean

Perform shallow clone, so that Git will not download the history of the project, saving time and disk space when you just want to access the latest version of a repository.

noTags

boolean

Deselect this to perform a clone without tags, saving time and disk space when you just want to access what is specified by the refspec.

reference

String

Specify a folder containing a repository that will be used by Git as a reference during clone operations. This option will be ignored if the folder is not available on the controller or agent where the clone is being executed.

timeout

int

Specify a timeout (in minutes) for clone and fetch operations.

This option overrides the default timeout of 10 minutes.

You can change the global git timeout via the property org.jenkinsci.plugins.gitclient.Git.timeOut. Property should be set on both controller and agent to have effect.

depth (optional)

int

Set shallow clone depth, so that Git will only download recent history of the project, saving time and disk space when you just want to access the latest commits of a repository.

honorRefspec (optional)

boolean

Perform initial clone using the refspec defined for the repository. This can save time, data transfer and disk space when you only need to access the references specified by the refspec.

RefSpecTemplate object

Ref Spec

Table 17. RefSpecTemplate object parameters
Parameter Type Description

value

String

A ref spec to fetch. Any occurrences of @{remote} will be replaced by the remote name (which defaults to origin) before use.

SparseCheckoutPath object

Path

Table 18. SparseCheckoutPath parameters
Parameter Type Description

path

String

SparseCheckoutPaths object

Specify the paths that you’d like to sparse checkout. This may be used for saving space (for example, a reference repository). Be sure to use a recent version of Git, at least above 1.7.10.

Table 19. SparseCheckoutPaths object parameters
Parameter Type Description

sparseCheckoutPaths

List of Nested SparseCheckoutPath object

SubmoduleOption object

Advanced submodules behaviors.

Table 20. Submodule object parameters
Parameter Type Description

disableSubmodules

boolean

By disabling support for submodules you can still keep using basic Git plugin functionality and just have Jenkins ignore submodules completely as if they didn’t exist.

recursiveSubmodules

boolean

Retrieve all submodules recursively (uses '--recursive' option which requires Git version 1.6.5 or higher).

trackingSubmodules

boolean

Retrieve the tip of the configured branch in .gitmodules (uses '--remote' option which requires Git version 1.8.2 or higher).

reference

String

Specify a folder containing a repository that will be used by Git as a reference during clone operations.

This option will be ignored if the folder is not available on the controller or agent where the clone is being executed.

To prepare a reference folder with multiple subprojects, create a bare Git repository and add all the remote urls then perform a fetch using the following commands:

git init --bare
git remote add SubProject1 https://gitrepo.com/subproject1
git remote add SubProject2 https://gitrepo.com/subproject2
git fetch --all
▼

timeout

int

Specify a timeout (in minutes) for submodules operations.

This option overrides the default timeout of 10 minutes.

You can change the global git timeout via the property org.jenkinsci.plugins.gitclient.Git.timeOut. Property should be set on both controller and agent to have effect.

parentCredentials

boolean

Use credentials from the default remote of the parent project.

depth (optional)

int

Set shallow clone depth, so that Git will only download recent history of the project, saving time and disk space when you just want to access the latest commits of a repository.

shallow (optional)

boolean

Perform shallow clone, so that Git will not download the history of the project, saving time and disk space when you just want to access the latest version of a repository.

threads (optional)

int

UserIdentity object

Custom user name/email address.

Table 21. UserIdentity object parameters
Parameter Type Description

name

String

If given, git config user.name [this] is called before builds. This overrides whatever is in the global settings.

email

String

If given, git config user.email [this] is called before builds. This overrides whatever is in the global settings.