Filtering using Bitbucket

Branch Options

The Branch Options field in the hook is whats recommended for filtering out which branches trigger Jenkins. You can choose to either whitelist (include) a specific set of branches or blacklist (exclude) a specific set of branches.

For example, if I want only commits to my release branches to trigger builds I would set Branch Options to Build From: with the field value release/* or Build RegEx: with a field value release/.+

 

Omit Branch Name

If the web hook doesn’t send the branches parameter to Jenkins, Jenkins will start all jobs with matching clone urls.

So if your build process doesn’t depend on branch then ‘Omit Branch name’ can be checked. Git performs checkout based on commit id so it ensures that correct change are built every time.

Filtering using Jenkins

You can also filter the branches to build on the Jenkins side.

The "Branches to Build" parameter (Git Plugin Only)

The Branches to Build parameter is used to associate Jenkins jobs with particular branches. It can be used in pair with the Git Plugin for Jenkins.

Each job configuration has a Branches to build parameter used to filter out commits so that certain jobs are only triggered for certain branches. This is useful, for example, when you want you have two separate jobs, one for the master branch and another one for the develop branch. The first job should be configured to build master only and the other can be configured to only build commits related to develop.

When commits are pushed to Bitbucket then plugin sends the associated branch name to Jenkins and it decides which job to run. By default, each Jenkins job is configured to build master and this can sometimes causes configuration issues for customers (i.e. you're wondering why your branch won't build, and it's because you haven't configured the job to build the other branches).

Example

Suppose you want to run one job for the master branch and another for any of the feature branches. Feature branches have names like feature/abc-1, feature/abc-2 .. etc.

This requires configuration below on Jenkins side:

Job name

Branches to build field in Jenkins job configuration

Feature job

origin/feature/*

Master job

origin/master

Technical Details

How the plugin sends the branch name

Historically the plugin uses the scheme below:

  • Branches use short form names like master, feature/ABC-123
  • For tags full from names are used refs/tags/release-1.0
  • For events associated with Pull Requests the plugin adds refs/pull-requests/<id>/from to the branch list, where id is pull request id. (Branches parameters can contain several branches delimited by commas).

The Trigger Jenkins button doesn’t send branch parameters. So if the Trigger Jenkins button launches the job but your actual commit doesn’t then first place to check is the Branches to Build parameter in your job.

How Jenkins matches branches

A lot of options are supported for branch matching. The Branches to Build field supports:

  • Use of environment variables
  • Wildcards (*)
  • Regular expressions

Given the way plugin sends branches parameter suggested format for branches is:

<remoteRepoName>/<branchName>

and for tags:

refs/tags/<tagName>

Pipeline job configuration (Bitbucket Branch Source Plugin)

Pipeline jobs may have no UI for specifying branches to build. Script analog is:

node {
    def scmVars = checkout([
               $class : 'GitSCM',
               branches : [[name: '*/master']],
               doGenerateSubmoduleConfigurations: false,
               extensions : [/*[$class: 'CleanBeforeCheckout']*/],
               submoduleCfg : [],
               userRemoteConfigs: [[credentialsId: 'local-bb', url: 'http://admin@localhost:7990/bitbucket/scm/project_1/rep_1.git']]
           ])
   stage('test') {
       println 'some text'
       println scmVars.GIT_BRANCH
   }
}
JS

Notice the branches parameter passed to the checkout call.

If you want the job to run build process for all branches set the branches parameter to an empty collection:  [ ]