Generate webHooks in BitBucket Server via REST API for Pipeline Multibranch

Issue

  • I want to create webhooks in BitBucket server to automatically trigger Multibranch or Bitbcuket Team/Project jobs on changes

Environment

Related Issues

Resolution

At the time of this article, there is no support for auto-registration of webhooks for Bitbucket server. This improvement is tracked by JENKINS-38748.

Until then, a workaround is to use the REST API implemented by the Post Webhooks for Bitbucket. Indeed this add-on exposes a REST API that can be leveraged to create webhooks for your repository/projects in Bitbucket Server. For more information about this REST API, you can see the source code in nl.topicus.bitbucket.api.WebhookResource.

This article provides basic commands that can be used to automate the generation of webhooks until JENKINS-38748 is resolved.

Variables

Following variable are used in this article to make commands as generic as possible. Update them accordingly to match your environment:

  • $USER/$PASSWORD: Username/Password of a Bitbucket user with sufficient permission to create webhooks
  • $BITBUCKET_SERVER_URL: The URL of the Bitbucket Server
  • $PROJECT: The Bitbucket project name
  • $REPO: The Bitbucket repository name
  • $WEBHOOK_ID: The id of an existing Webhook in a bitbucket repository

The webhook data when POSTing:

  • $TITLE: Title to give to the webhook
  • $ENABLED: true | false
  • $JENKINS_URL: The Jenkins URL

Example in the UI:

Get existing webhooks

Use the following command to get the existing webhooks of a project repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X GET $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations

This will return the list of existing webhooks in a JSON Array.

Example:

curl -u ‘user:password’ -H “Content-Type: application/json” -X GET https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations

Output:

[{“id”:22,“title”:“Jenkins Example”,“url”:"http://jenkins.example.com/bitbucket-scmsource-hook/notify“,”enabled":false}]

Create a webhook

Use the following command to create a new webhook for a repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X PUT -d ‘{“title”: “$TITLE”, “url”: “$JENKINS_URL/bitbucket-scmsource-hook/notify”, “enabled”: “$ENABLED”}’ $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations

This will return the created webhook in a JSON Object.

Example:

curl -u ‘user:password’ -H “Content-Type: application/json” -X PUT -d ‘{“title”: “http://jenkins.example.com", ”url“: ”http://jenkins.example.com/bitbucket-scmsource-hook/notify", “enabled”: “true”}’ https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations

Output:

{“id”:35,“title”:"http://jenkins.example.com","url":"http://jenkins.example.com/bitbucket-scmsource-hook/notify","enabled":true}

Update a webhook by ID

Use the following command to update an existing webhook of a repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X POST -d ‘{“title”: “$TITLE”, “url”: “$JENKINS_URL/bitbucket-scmsource-hook/notify”, “enabled”: “$ENABLED”}’ $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID

This will return the updated webhook in a JSON Object.

Example:

curl -u ‘user:password’ -H “Content-Type: application/json” -X POST -d ‘{“title”: “http://jenkins.example.com", ”url“: ”http://jenkins.example.com/bitbucket-scmsource-hook/notify", “enabled”: “false”}’ https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations/35

Output:

{“id”:35,“title”:"http://jenkins.example.com","url":"http://jenkins.example.com/bitbucket-scmsource-hook/notify","enabled":false}

Delete a webhook by ID

Use the following command to delete an existing webhook of a project repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X DELETE $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID

This should return nothing unless there is an issue.

Example:

curl -u ‘user:password’ -H “Content-Type: application/json” -X DELETE https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations/35

References

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.