Webhook to Jenkins for Bitbucket version 4.2 and higher support sending custom job parameters to Jenkins during the notification/trigger process adding them to notified Jenkins URL. To use this feature, you must also configure Jenkins to allow parameters.

The Job Parameter feature is only available when using the Git plugin and Direct Job Trigger endpoints. Bitbucket Branch Source plugin is not supported at this time.

Setup

Configuring Jenkins

Git Plugin for Jenkins version 2.5.0 and higher will by default reject all URL parameters. You must configure Jenkins to allow job parameters by doing ONE of the following:

  • Setting the Jenkins JVM switches -Dhudson.model.ParametersAction.keepUndefinedParameters=true and -Dhudson.plugins.git.GitStatus.allowNotifyCommitParameters=true. This allows arbitrary notify commit parameters (reference). Only enable this if you trust all unauthenticated users not to pass harmful arguments to your jobs.

  • Setting the Jenkins JVM switch -Dhudson.plugins.git.GitStatus.safeParameters=PARM1,PARM1. If this property is set to a comma-separated list of parameters, those parameters are allowed for any job. Only set this value for parameters you trust in all the jobs in your system.

For detailed instructions on adding Java arguments to Jenkins, see the CloudBees guide

Usage

Configure Bitbucket Server

  1. Log in to your Bitbucket repository and navigate to Repository Settings > Hooks > Enable or click the Edit setting for Webhooks to Jenkins Server icon.

  2. Click the  Advanced Configuration tab and locate Job Parameters at the bottom of the dialog.

  3. Enter the job parameter into the parameter field. The rules for the parameters are as follows:

    • The formatting for the parameter is DESIRED_VARIABLE_NAME={PARAMETER_NAME}

    • Every parameter starts on a new line.

    • The name given to your parameter is how you reference the parameter in Jenkins. In our example the parameter name is TARGET_BRANCH.

    • To pull information from Bitbucket to use as a parameter (like the branch name), refer to the Available parameters section and enter the parameter on the right side of the equal sign surrounded with curly braces {BRANCH_NAME}.

    • To use your own custom value, eliminate the curly braces and enter the value to the right of the equal sign.

You cannot use additional parameters together with the Omit SHA1 Hash Code option enabled with Git endpoint. This case is not supported on the Jenkins side.

Configure Jenkins

To access the parameter in your Jenkins job:

  1. Go to your job, click Configure from the left sidebar and go to the General tab. Select This project is parameterized.

  2. click Add Parameter and select String Parameter

  3. in the Name field, enter the name of the parameter that you used in the Webhook to Jenkins Job Parameters field.

  4. For each additional parameter, click Add Parameter, select String Parameter and enter the name of the next parameter.

  5. Click Save.

Your parameters should now be passed to Jenkins.

Available Parameters

To pull information from Bitbucket to use as a parameter (like the branch name), refer to the table below and put the parameter on the right side of the equal sign and surround it with curly braces.

For example, TARGET_BRANCH={PR_DESTINATION}, where PR_DESTINATION is the branch name of the destination branch.

Parameter

Description

PR_SOURCE 

The branch name of the source branch (Only available in pull requests).

PR_DESTINATION 

The branch name of the destination branch (Only available in pull requests).

PR_SOURCE_COMMIT

The most recent commit id/reference for the source branch (Only available in pull requests).

PR_DESTINATION_COMMIT

The most recent commit id/reference for the destination branch (Only available in pull requests).

PR_ID

The pull request ID number (Only available in pull requests).

PR_URL

The URL of the pull request (Only available in pull requests).

PR_TITLE

The title of the pull request (Only available in pull requests).

PR_ACTION

The action that triggered build for the pull request (Only available in pull requests).

PR_VERSION

The version of the pull request (Only available in pull requests).

PR_REVIEWERS

The pull request reviewer display names (Only available in pull requests).

PR_REVIEWERS_SLUG

The pull request reviewer slugs (Only available in pull requests).

REPOSITORY

The repository being affected by the event.

PROJECT

The project the repository being affected by the event is located in.

BRANCH

The branch associated with the event.

COMMIT

The commit id/reference associated with the event.

USER

The username of the user who initiated the event.

USER_EMAIL

The email of the user who initiated the event.

BB_URL

The base URL of the Bitbucket instance hosting the affected repository.

BB_PORT

The network port of the Bitbucket instance hosting the affected repository.