Bitbucket

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.

Discovers branches and/or pull requests from a specific repository in either Bitbucket Cloud or a Bitbucket Server instance.

Table 1. Bitbucket parameters
Parameter	Type	Description
`repoOwner`	String	Specify the name of the Bitbucket Team or Bitbucket User Account. It could be a Bitbucket Project also, if using Bitbucket Server. In this case (Bitbucket Server): Use the project key, not the project name. If using a user account instead of a project, add a "~" character before the username, for example, "~joe".
`repository`	String	The repository to scan.
`autoRegisterHook` (optional)	boolean
`bitbucketServerUrl` (optional)	String
`checkoutCredentialsId` (optional)	String
`credentialsId` (optional)	String	Credentials used to scan branches (also the default credentials to use when checking out sources).
`excludes` (optional)	String
`id` (optional)	String
`includes` (optional)	String
`serverUrl` (optional)	String	The server to connect to. The list of servers is configured in the Manage Jenkins » Configure Jenkins › Bitbucket Endpoints page. The list of servers can include both Bitbucket Cloud as well as Bitbucket Server instances.
`traits` (optional)	List of Nested Choice of SCM Source Trait objects	The behaviors control what is discovered from the Bitbucket repository. The behaviors are grouped into a number of categories:

SCM Source Trait 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.
bitbucketPublicRepoPullRequestFilter

If the repository being scanned is a public repository, this behavior will exclude all pull requests. This behavior is not especially useful if scanning a single repository as you could just not include the pull request discovery behaviors in the first place.
bitbucketWebhookConfiguration

Sets the value for committersToIgnore in the Bitbucket Webhook. Value should be a comma separated string. committerToIgnore is used to prevent triggering Jenkins builds when commits by certain users are made.

Table 12. bitbucketWebhookConfiguration parameters

Parameter Type Description

committersToIgnore

String

Table 12. `bitbucketWebhookConfiguration` parameters
Parameter	Type	Description
`committersToIgnore`	String

bitbucketWebhookRegistration

Overrides the defaults for webhook management.

Webhooks are used to inform Jenkins about changes to repositories. There are two ways webhooks can be configured:

Manual webhook configuration requires the user to configure Bitbucket with the Jenkins URL in order to ensure that Bitbucket will send the events to Jenkins after every change.

Automatic webhook configuration requires that Jenkins has credentials with sufficient permission to configure webhooks and also that Jenkins knows the URL that Bitbucket can connect to.

The Manage Jenkins » Configure Jenkins › Bitbucket Endpoints page allows defining the list of servers. Each server can be associated with credentials. If credentials are defined, then the default behavior is to use those credentials to automatically manage the webhooks of all repositories that Jenkins is interested in. If no credentials are defined then the default behaviour is to require the user to manually configure webhooks.

Table 13. `bitbucketWebhookRegistration` parameters
Parameter	Type	Description
`mode`	String	There are two available modes: Disable hook management Disables hook management irrespective of the global defaults. Use item credentials for hook management Enables hook management but uses the selected credentials to manage the hooks rather than those defined on the Manage Jenkins » Configure Jenkins › Bitbucket Endpoints page.

bitbucketBranchDiscovery

Discovers branches on the repository.

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, it may not make sense to discover the same changes both as a pull request and as a branch.
Only branches that are also filed as PRs

This option exists to preserve legacy behavior when upgrading from older versions of the plugin.

If you have an actual use case for this option please file a pull request against this text.
All branches

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

bitbucketForkDiscovery

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

Table 15. `bitbucketForkDiscovery` parameters
Parameter	Type	Description
`strategyId`	int	Determines how pull requests are discovered including the following ways: Merging the pull request with the current target branch revision (strategyId: 1) 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 (strategyId: 2) 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.

bitbucketPullRequestDiscovery

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

Table 16. `bitbucketPullRequestDiscovery` parameters
Parameter	Type	Description
`strategyId`	int	Determines how pull requests are discovered, including the following ways: 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.

bitbucketSshCheckout

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/Mercurial 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.

Table 17. bitbucketSshCheckout parameters

Parameter Type Description

credentialsId

String

Credentials used to checkout sources. Must be a SSH key-based credential.
bitbucketTagDiscovery

Discovers tags on the repository.

Table 17. `bitbucketSshCheckout` parameters
Parameter	Type	Description
`credentialsId`	String	Credentials used to checkout sources. Must be a SSH key-based credential.

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: 'TrustTeamForks'

Bitbucket allows for a repository to be forked into a "sibling" repository in the same account but using a different name. This strategy will trust any pull requests from forks that are in the same account as the target repository on the basis that users have to have been granted write permission to account in order create such a fork.
$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 Bitbucket Cloud.

Nested objects

CheckoutOption object

Advanced checkout behaviors.

Table 18. 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 19. 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 20. 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 21. 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 22. SparseCheckoutPaths object parameters
Parameter	Type	Description
`sparseCheckoutPaths`	List of Nested SparseCheckoutPath object

SubmoduleOption object

Advanced submodules behaviors.

Table 23. 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 24. 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.