GitHub

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

Table 2. `CheckoutOptionTrait` parameters
Parameter	Type	Description
`extension`	Nested CheckoutOption object

Table 3. `CloneOptionTrait` parameters
Parameter	Type	Description
`extension`	Nested CloneOption object

Table 4. `GitToolSCMSourceTrait` parameters
Parameter	Type	Description
`gitTool`	String

Table 5. `RefSpecsSCMSourceTrait` parameters
Parameter	Type	Description
`templates`	List of Nested RefSpecTemplate object

headRegexFilter

Filter by name (with regular expression)

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

Table 7. `RemoteNameSCMSourceTrait` parameters
Parameter	Type	Description
`remoteName`	String

Table 8. `SparseCheckoutPathsTrait` parameters
Parameter	Type	Description
`extension`	Nested SparseCheckoutPaths object

Table 9. `SubmoduleOptionTrait` parameters
Parameter	Type	Description
`extension`	Nested SubmoduleOption object

Table 10. `UserIdentityTrait` parameters
Parameter	Type	Description
`extension`	Nested UserIdentity object

headWildcardFilter

Filter by name (with wildcards)

Parameter Type Description

includes

String

Space-separated list of name patterns to consider. You may use * as a wildcard; for example: main 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.