Bitbucket

9 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.

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

  • $class: 'CleanAfterCheckoutTrait'

    Clean after checkout.

  • $class: 'CleanBeforeCheckoutTrait'

    Clean before checkout.

  • $class: 'CloneOptionTrait'

    Advanced clone behaviors.

    Table 3. CloneOptionTrait parameters
    Parameter Type Description

    extension

  • $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

  • $class: 'SubmoduleOptionTrait'

    Advanced sub-modules behaviors

    Table 9. SubmoduleOptionTrait parameters
    Parameter Type Description

    extension

  • $class: 'UserIdentityTrait'

    Custom user/e-mail address.

    Table 10. UserIdentityTrait parameters
    Parameter Type Description

    extension

  • 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: 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

  • 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.

Table 14. bitbucketBranchDiscovery 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, 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.

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.