Skip to main content
All CollectionsUsing Assembla Integrations
Configure Jenkins CI Integration with Merge Requests
Configure Jenkins CI Integration with Merge Requests
Toshi Dávila avatar
Written by Toshi Dávila
Updated over 5 years ago

What is the Assembla Merge Request Builder Plugin?

A Jenkins plugin that reads Assembla merge requests, builds and tests the modified software, and writes results to Assembla with an upvote or downvote on the merge request, a comment on related tickets, or custom messages.
​

This plugin fetches the source and target branches of an Assembla merge request and makes them available to your build via build parameters. Once the build completes, Jenkins will leave a comment on the merge request and related tickets indicating whether the merge request was successful or not.
​
​ Note: This plugin works with GIT repositories only.
​

Required Jenkins plugins

You can learn more about our git plugin here: https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin
​

Installation

Ensure that the user you wish to connect with Jenkins exists within your Assembla space, has access to the repository, and has permissions to leave comments. Furthermore, ensure that the user has Member level access to the project.

Install the plugin in Jenkins

  1. The plugin is hosted on the Jenkins Plugin repository

  2. Go to Jenkins > Manage Plugins > Available

  3. Search for Assembla Merge Request Builder

  4. Install it

  5. Ensure you restart Jenkins

  • Go to Manage Jenkins > Configure System > Assembla Merge Request Builder

  • Set your User API key for the Jenkins user. This can be found by logging into Assembla with the user you plan to integration Jenkins with and going to the profile page.

Set your User API secret for the Jenkins user. This can be found the same way as the User API Key.

Note: If you are hosted in the Assembla EU zone, you will need to make sure that Assembla host reads https://eu-app.assembla.com

  • Click Test credentials button to check

  • Set/change any of the other available parameters as necessary.

  • Save to preserve your changes.

  • Go to Manage Jenkins > Configure Global Security and set Markup Formatter to Safe HTML. It will make Jenkins properly display links in build history.

Webhooks

  1. Make sure that you have Webhook Tool installed and you have a git repository in your space already. If you haven’t installed it yet, go to Admin > Tools > More > Webhook section and click the Add button.

  2. Set Assembla webhook to trigger your Jenkins server. Go to https://app.assembla.com/spaces/{your_space_name}/webhooks. Click Create New Webhook, select Assembla Jenkins plugin from template, change your Jenkins server URL (Make sure Code comments and Code commits are checked in Post updates about section), enable it and click the Add button.

3. You only need to configure the Webhook Tool once per space.
4. If you are using the Jenkins server behind a firewall, you need to add the IP range of our servers to your whitelist. Please contact the Assembla Support team for this information at support@assembla.com.
​

Creating a Job

  1. Create a new job by going to New Job

  2. Set the Project Name

  3. In the Source Code Management section, click Git, enter your Repository URL and in Advanced, set its Name to origin

In Branches to build, enter: origin/${assemblaSourceBranch}

4. OPTIONAL: To build merge requests from forked repositories, change Branches to build field to ${assemblaSourceRepositoryName}/${assemblaSourceBranch}, add another repository with Repository URL ${assemblaSourceRepositoryUrl}and name ${assemblaSourceRepositoryName}

5. OPTIONAL: You can configure jenkins to merge the source with the target branch before your build. In the Additional Behaviours section:

  1. Click the Add drop down button and the Merge before build item

  2. Specify the name of the repository as origin and enter the branch to merge to as ${assemblaTargetBranch}

  3. NOTE: ${assemblaTargetBranch} parameter is not available when using Push trigger

  4. Ensure Prune stale remote-tracking branches is not added.

6. In the Build Triggers section:

  1. Check the Assembla Triggers and Assembla Merge Request Builder configuration section will appear.

  2. Enter Space name and Repository name and click Check settings button. For example: If your code browser url is https://app.assembla.com/spaces/pavel-test/git/source The space name will be pavel-test and repo name - git.

  3. Check Comment and vote merge request to allow Jenkins to post a comment about build results and upvote/downvote merge requests.

  4. If you want to be notified when Jenkins starts the build, check the Comment after job start checkbox. Jenkins will post a comment to a merge request and related tickets (if Comment related tickets checkbox is checked).

7. Configure any other pre build, build, or post build actions as necessary.
8. Click Save to preserve your changes.
​

Manual Triggers

You can trigger a job a manually by clicking This build is parameterized and adding the relevant build parameters. These include:

  • $assemblaSourceRepositoryUrl - assembla repository url

  • $assemblaTargetBranch - merge request target branch

  • $assemblaSourceBranch - merge request source branch

Note: A manually triggered build will not add build triggered/succeeded/failed comments to the merge request.
​
​Note: You should ensure that the 'Global Config user.name Value' and 'Global Config user.email Value' are both set for your git plugin. In some cases, you will get an error indicating that a branch cannot be merged if these are not set.
​

Message templates

Plugin allows to customize all build messages and build description using templates (Manage Jenkins > Configure System > Assembla Merge Request Builder). You can use any env variables or build parameters in templates. For example, you can mention your QA team to test changes or mention merge request author about build result etc.


Additionally, the plugin provides:

  • $mrTitle - merge request title

  • $mrAbbrTitle - merge request title truncated to 30 chars

  • $mrUrl - merge request url

  • $mrId - merge request id

  • $jobName - jenkins job name

  • $buildStatus - build status (available only if build is completed)

  • $buildUrl - build url

  • $assemblaSourceSpaceId - assembla space id

  • $assemblaDescription - merge request description

  • $assemblaSourceRepositoryUrl - assembla repository url

  • $assemblaTargetBranch - merge request target branch

  • $assemblaSourceBranch - merge request source branch

  • $assemblaMergeRequestId - assembla merge request id

  • $assemblaRefName - build git revision

Contributing

If you have any ideas, feel free to contribute. The plugin is open-source! Check the repository readme for detailed instructions.
​
​


If you have any questions or need assistance, please always feel free to email us at support@assembla.com. We will be happy to assist.

Did this answer your question?