Trigger Jenkins for commits to a specific branch

Filter the branches that can trigger a build in Jenkins by either including or excluding a specific set of branches using the Branch Options feature from the Webhook to Jenkins Advanced Configuration tab.

Filtering using Bitbucket

Branch Options

The Advanced Configuration > Branch Options field in the hook is recommended for filtering out which branches trigger Jenkins. Choose to allowlist (include) a specific set of branches or blocklist (exclude) a specific set of branches.

Examples

• Branch Options set to Build From: with the field value "release/* feature/*" - All release and feature/ branches will trigger builds (e.g. release/test-123, feature/test-55 etc.)

• Branch Options set to Build RegExp: with the regexp field value "(release|bugfix)/.+" -  All release/ and bugfix/ branches will trigger builds (e.g. release/test-123, bugfix/test-455 etc.)

• Branch Options set to Ignore from: with the field value "develop/*" - All branches except develop/ will trigger builds (e.g. develop/test-123 etc. will NOT triggered builds)

• Branch Options set to Ignore RegExp: with the regexp field value "(hot)?fix/.+" - All branches except hotfix/ and fix/ will trigger builds (e.g. fix/test-123, hotfix/test-123 etc. will NOT triggered builds)

From your repository, click the Repository Settings icon > Hooks and select Enabled or edit the previously enabled Webhook to Jenkins configuration. Click the Advanced Configuration tab.

Select a branch option from the dropdown. Use separator / between items and * for a wildcard at the end of each item.

When using the Direct Job Trigger endpoint with mutibranch job, hook also applies branch filter to the list of directly selected branch-jobs.

Omit branch name

If the web hook doesn’t send the branches parameter to Jenkins, Jenkins starts all jobs with matching clone URLs.

If your build process does not depend on branch, you can select the Omit Branch Name option. Git performs a checkout based on the commit ID to help ensure the correct changes are built every time.

Click the General Settings tab and select the Omit Branch Name option.

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 Jenkins job configuration has a Branches to build parameter (Jenkins job > Configure > Source Code Management > Branches to Build), which is used to filter out commits so that certain jobs are only triggered for certain branches. This is useful, for example, with two separate jobs, one for the master branch and another for the develop branch. Configure the first job to only build master and the other to only build commits related to develop.

When commits are pushed to Bitbucket the plugin sends the associated branch name to Jenkins, which decides which job to run. By default, each Jenkins job is configured to build master, which can sometimes causes configuration issues for customers (i.e. if the branch won't build, it's because you haven not 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 on Jenkins side:

Technical details

How Webhook to Jenkins sends the branch name

The plugin uses the following scheme:

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

Test Configuration does not send branch parameters. If Test Configuration launches the job but the actual commit does not, check the Branches to Build parameter in your job.

How Jenkins matches branches

Multiple options are supported for branch matching. The Branches to Build field supports:

• Use of environment variables

• Wildcards (*)

• Regular expressions

Follow the recommend naming convention for branches:

<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. The 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
   }
}

Notice the branches parameter passed to the checkout call.

To make the job to run build process for all branches, set the branches parameter to an empty collection:  [ ]

Refer to the Pipeline section of the Jenkins documentation for more information.