# Use the JIRA integration

> Track Jira issues across branches or changesets.

Choose a workflow for your JIRA integration to link tickets and transition statuses.

Use one of the following working modes for your JIRA integration:

* [Task on branch](#task-on-branch-workflow)
* [Task on changeset](#task-on-changeset-workflow)

You can also [transition JIRA statuses](#transition-jira-statuses).

Find issue information in the JIRA extension panel. You can open the issue in the browser, add a new issue, or delete an issue. If you select the **Open issue in browser** icon, or double-click on the JIRA task, UVCS opens the associated issue in a browser window. JIRA displays the details of any changes in the linked issue, under the custom field.

## Task on branch workflow

Task on branch is the default working mode. Each JIRA task links to a branch in Unity Version Control (UVCS).

### Link a branch to an issue

1. [Create a JIRA issue](https://www.atlassian.com/agile/tutorials/issues). JIRA assigns a number to each issue.
2. Create a branch that links to JIRA:
   1. Select **Manual** to enter a branch name that matches the number of the JIRA issue, preceded by the configured branch prefix. For example, if you configured the branch prefix `task`, and the JIRA issue number is 4, name the branch `task004`.
   2. Select **From task** to select an existing JIRA task.

If you select the **Open issue in browser** icon, or double-click on the JIRA task, UVCS opens a browser window with the associated branch issue.

## Task on changeset workflow

The task on changeset working mode allows you to link multiple changesets to multiple branches.

### Link a changeset to an issue

Use the UVCS desktop application to link changesets to JIRAissues:

1. Make the changes in UVCS.
2. On the **Pending Changes** tab, select **Show tasks** to open the tasks side panel.
3. Select the **Add new issue** (**+**) icon.
4. Select issues from the list of pending tasks, or enter a comma-separated ID list if you can’t find the correct issue.
5. Select **OK**.

To log the checkin information in the related JIRA issue, enter a comment in the **Checkin comments** field, start the comment with the `#` character followed by the issue key. For example, `VCS-1: update`.

## Transition JIRA statuses

Use changeset comments in Unity Version Control (UVCS) to change the status of a linked issue in the JIRA integration. Your JIRA workflow must allow these transitions.

### Configure status transitions

Define your own keyword-status mappings so that if the keyword is in the changeset comment, the issue status transitions to the status mapped to that keyword.

#### Map keyword-status pairs on Windows

Configure the status transitions in the UVCS desktop application:

1. Select the context menu, then select **Preferences**.
2. Select **Issue trackers**.
3. Enter the [keyword-status pairs](#status-transition-syntax) in the **Status transitions** field.

#### Map keyword-status pairs on Linux or macOS

1. Open the `jira.conf` file.
2. Add the following line and replace the text in the value parameter with the required [keyword-status pairs](#status-transition-syntax):
   ```text
   Name=Status transitions;Value=[FIXED]-Ready for QA|[WONTFIX]-Done;Type=Text;IsGlobal=True
   ```

### Status transition syntax

Use the following format for the keyword-status mapping:

```text
[<KEY>]-<VALUE>|[<KEY>]-<VALUE>
```

For example, the following keyword-status mapping configures the following transitions:

* If a comment includes the keyword `FIXED`, the issue transitions to the **Ready for QA** JIRA status.
* If a comment includes the keyword `WONTFIX`, the issue transitions to the **Done** status.