Documentation

This is the documentation for the Atlassian Jira Add-on Merge Agent for Jira.

Installation

Head to the settings within Jira. Note that administrator privileges are required to access the settings.

In the menu on the left side, navigate to “Find new apps” under the “apps” category. Search for “Merge”, wait until the entry “Merge Agent for Jira” is shown and proceed to “Install” the app.

Merging

After having installed the add-on from the Atlassian Marketplace, you can start using it right away! Just navigate to a Jira issue of your choice and click on the “Merge” button on the upper right-hand corner of the issue.

New Jira Issue View

Old Jira Issue View

The following dialog will appear:

You’re then able to configure how the issue should be merged. Specify the issues to merge into, along with which fields and other embedded content from the issue should be merged, including:

• Attachments
• Comments
• Issue links
• Votes
• Watchers
• Work log

You’ll see in parentheses next to these how many of a content type would be merged, e.g. “Attachments (3)” would show that we’ve detected 3 attachments that would be merged if the checkbox is activated. For comments and the work log, you can select that the original time the comment was created at will be added to the comment as the first line (since the comments themselves will be shown as being created when you merge the issue).

Once you click the “Merge” button, you can see how we merge the fields and content into the other issues:

You may close the dialog at any time without the merging process to be interrupted. Note however that if you start editing the issue right away, your changes may be overwritten until the merging process is finished.

Permissions

By default, all logged-in users can use Merge Agent for Jira. You can restrict permissions either globally or per project. A user has access by either having global permissions or project permissions, they don’t need both permissions.

Global Permissions

Navigate to the “Global Permissions” within the Jira System settings. At the bottom, you will find the “Merge Agent for Jira” permission. A user with this permission will be able to access Merge Agent for Jira for all issues in all projects, no matter how project permissions are configured.

Project Permissions

Navigate to the Permission scheme of a project. At the bottom, you will again find the “Merge Agent for Jira” permission. A user with this permission will be able to access Merge Agent for Jira for all issues within the projects using this permission scheme, no matter how global permissions are configured.

Scopes

A Merge Agent for Jira installation requires the following scopes:

• “Read” is required to get information about the original issues, e.g. project configuration. Merge Agent uses that information to prepare the merge dialog and prevent errors.
• “Write” enables Merge Agent to add information from one ticket to another.
• “Admin” is required to get information about workflows. It also enables Merge Agent to edit tickets that cannot be edited by a normal Jira user (e.g. closed tickets).
• “Act as user” is required to merge comments, making them appear as if they were added by their original author .

You can read more about scopes in the Atlassian Developer documentation.

Known problems

We try our best to merge fields with as little deviation from the original issue as possible. Unfortunately due to some limitations of Jira, a few problems remain where we cannot merge all content of existing issues:

• Comments and worklogs with restricted visibility will not be merged.
• Some ServiceDesk and other custom field types can not be merged.

Support

If you encounter any further problems or any kind of feedback, feel free to contact our support team. We’ll usually reply within one business day.

Thanks for using Merge Agent for Jira!