Send URL parameters to Jenkins

Owned by Jeff Gleeson
Last updated: Nov 22, 2023
3 min read

Webhook to Jenkins for Bitbucket Cloud now supports sending custom URL parameters to Jenkins during the notification/trigger process. To use this feature, you must configure Jenkins to allow URL parameters.

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

  • The URL parameter feature for Webhook to Jenkins for Bitbucket Cloud only supports the PR_destination (target branch) parameter.

Setup

Configure Jenkins to allow job parameters

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

  • Set the Jenkins JVM switches -Dhudson.model.ParametersAction.keepUndefinedParameters=true and -Dhudson.plugins.git.GitStatus.allowNotifyCommitParameters=true. This allows arbitrary notify commit parameters (reference). 

  • Set 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 these switches if you trust all unauthenticated users not to pass harmful arguments to your jobs.

For detailed instructions on adding Java arguments to Jenkins, see How to add Java arguments to Jenkins?. 

Usage

Configure Bitbucket Server

  1. Log in to Bitbucket Cloud. Click the Settings icon and select Workspace settings.

  2. Click Webhook to Jenkins for Bitbucket. If you have not created a connection, refer to Configure Webhook to Jenkins for Bitbucket Cloud for instructions.

  3. Click Hook Settings and add the job parameter to an existing instance by locating an entry from the list and clicking the Options icon > Edit. If you need to create a new instance, refer toConfigure Webhook to Jenkins for Bitbucket Cloudfor instructions.

  4. Click Settings.

  5. Under the Job parameters heading, enter the Parameter name. This is the same name used when configuring the parameter name in Jenkins.

  6. Select a predefined parameter or type in a parameter value. You can create a custom value by entering a string value containing any text that is not the same as a predefined parameter. This parameter must also be defined in Jenkins. See Configure Jenkins for more information.

  7. Click Add.

  8. The name and value are added to the Job parameters list. Any custom value has a CUSTOM label attached when it appears in the list.

  9. Click the Trash icon to remove the entry from the list.

Available Parameters

The available parameters available for Webhook to Jenkins for Bitbucket Cloud is limited compared to the Data Center version. Additional parameters will be added in future releases.

Parameter

Description

Parameter

Description

PR_DESTINATION 

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

PR_SOURCE 

The branch name of the source 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_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.

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 URL 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 are now passed to Jenkins.