Jira Data Center

With Jira Data Center, you have the choice between authentication by username and password and authentication by personal access token.

If you want to authenticate via Personal Access Token, then proceed as follows to create the Personal Access Token. Open your Jira instance, log in, and then click on your avatar in the upper right corner, then click on Profile.

../../../_images/jira_data_center_001.png — Jira dropdown menu after clicking on the avatar in the top right corner.

In your user profile click on Personal Access Tokens in the sidebar, then on the Create token button, and fill out the form as follows.

../../../_images/jira_data_center_002.png — Jira dialog for creating a personal access token.

Token Name: The name of the personal access token can be chosen freely.
Automatic expiry: Uncheck this checkbox so that the token never expires.

After filling in everything, click on Create. You will then see the newly created Personal Access Token. Copy it, the token is needed to complete the configuration in MergeBoard.

Back in MergeBoard, fill out the form as follows.

Name: The name will be displayed when referencing an issue of the respective issue tracker. Make sure to give it a distinctive name, as you can add multiple issue trackers of the same type.
Type: Must be Jira.
Authentication: You can choose between Authenticate with Username and Password and Authenticate with Personal Access Token.
Jira URL: Full URL of your Jira Data Center instance, e.g., https://jira.mycompany.com. The input of a trailing slash is not necessary.
Username / Password: Only available if you have selected Authenticate with Username and Password. Enter your user name (not your email address!) and the corresponding password.
Personal Access Token: Only available if you have selected Authenticate with Personal Access Token. Paste the personal access token you created earlier in Jira.
Project: Optionally enter a project key here. When a project key has been entered, only issues of the respective project can be accessed from MergeBoard. If you leave the field empty, issues from all projects that the Jira user has access to can be used in MergeBoard. You can view the project key in Jira by clicking on Projects in the navigation bar and then on View All Projects.

../../../_images/jira_data_center_003.png — You can see the project keys in the list of all projects.

Review Status

Name of the status to be assigned to Jira issues when they are referenced in a merge request. If you do not want to change the status automatically, just leave this field empty.

To determine the value to insert, go to the respective project in Jira, and then to Project settings in the sidebar on the left. Click on Workflows and select the workflow to edit (usually there is exactly one). Either copy the name of an existing status that you want to use for merge requests in review (e.g. “In Progress”) or add a new status by clicking on Edit and then on Add status.

In MergeBoard, the name of the status must be specified exactly as in Jira. Capitalization is ignored, so both “IN REVIEW” and “In Review” have the same effect.

Note that if MergeBoard was instructed to make a status transition that is not allowed in Jira, the status of the issue will be left untouched.

../../../_images/jira_data_center_004.png — Jira workflow editor to customize statuses and transitions. MergeBoard can be configured to automatically update the issue status when a merge request is opened.

Merged Status

Analogous to “Review Status”, this is the status to be assigned once the merge request in MergeBoard has been merged. If you do not want to change the status automatically, just leave the field empty.

When using the default Jira workflow, the status usually is “Done”.

Merge Request Field

If desired, MergeBoard can store a link to the merge request in Jira. To use this feature, you must first create a custom field in Jira, which is then set via MergeBoard.

Click on Plans in the top navigation bar and then on Administrations. Then select the Issues tab and Custom fields in the left sidebar. Click Add custom field to open the dialog for creating a new field. In the first step, select URL and click Next. In the second step, enter a name for the field, e.g. “Merge Request URL”, and optionally a description before clicking on Next. In the last step you can specify if the custom field should only be added for certain projects or if it should be available for all projects of the Jira instance.

../../../_images/jira_data_center_005.png — Dialog for adding a new custom field in Jira.

Once this is done, click Field configurations in the sidebar on the left, select the respective configuration (usually “Default Field Configuration”), and then search for your newly added field (e.g., “Merge Request URL”) and click on Screen. Enable the Merge Request URL field for all screens where the field should be displayed.

../../../_images/jira_data_center_006.png — Dialog for associating field to screens.

In MergeBoard you simply have to enter the name of the field (e.g. “Merge Request URL”). If you do not want to use this feature, you can leave the field empty.

Comment

If this checkbox is set, MergeBoard automatically creates a comment that points to the merge request URL. If you also store the merge request URL in a custom field, you can usually disable this option (unless you want both for redundancy).

Once you are happy with the settings click on Save.