JIRA

JIRA is a well-known issue tracking tool by Atlassian. Many large organizations use it for tracking work at multiple levels. JIRA offers limitless possibilities for configuring workflows and levels of work to match even the most complicated needs enterprises might have.

By comparison, issue tracking in Helix TeamHub takes on a much simpler approach. TeamHub strives to solve even the most complex problems with the simplest solution possible.

This section describes how to set up a JIRA hook to use JIRA smart commits.

Smart commits

Helix TeamHub supports interoperability between the code commits made to TeamHub's Git, Subversion or Mercurial repositories and tickets that are maintained in JIRA. The interoperability between TeamHub and JIRA happens through smart commits, which allow processing JIRA issues with commit messages. Smart commits allow developers to perform actions such as transitioning or commenting on JIRA issues by embedding specific commands into commit messages.

With TeamHub smart commits, you can:

  • Comment on issues.
  • Record time tracking information against issues.
  • Transition issues to any status defined in the JIRA project's workflow.

You can also:

  • Add, set, or remove a version and fixed version, components, and labels for a given issue.
  • Set the assignee, description, priority, reporter, summary, or resolution for an issue.

Setting up smart commits

Smart commits work through a post-commit hook that you add and configure against a given repository and JIRA server from the Hooks tab in a TeamHub project. You can add hooks to any version control system repository.

JIRA hook in Helix TeamHub hooks

To add a JIRA hook, you need the following information:

  • The URL of the JIRA server

  • The username of the Jira user

  • The API token or password of the Jira user

    Tip
    • If you are connecting to Jira Cloud, you must enter an API token.
    • For different JIRA and TeamHub projects, different credentials might be required.

Smart commit commands basics

Smart commits are read from commit messages, which follow this basic syntax:

<any text> <ISSUE_KEY> <any text> #<COMMAND> <optional COMMAND_ARGUMENTS>

Following is a simple example for commenting on a JIRA issue with a commit:

JR-456 #comment this is a comment to the JIRA ticket.

The commit above references the JIRA issue and also leaves a comment inside the issue. The following figure illustrates the comment specified with the #comment verb as well as the separate reference that links the JIRA issue to the respective commit. You can click the link to open the code changes in TeamHub.

Commit in Helix TeamHub referencing a JIRA issue

The following commit provides a more complex usage example: It transitions the issue, comments on it, and adds more time.

JR-456 #to-do #comment Still not working #time 1d 4.5h 10m It takes too much time!

Connecting JIRA smart commits to code reviews.

You can also leverage JIRA smart commits for the daily development workflow by having JIRA issues transition from one state to another when a code review in TeamHub is merged. To accomplish this, you need to add a JIRA smart commit transition to the description of the code review. The following screenshot illustrates a done transition for JIRA issue #JR-456.

Helix TeamHub code review that will transition a JIRA issue once merged

This works because in TeamHub, the code review description is always included in the merge commit that is created when the code review is merged. Because the description contains the transition information, the JIRA hook works as it would work for any other commit, as does the transition.