Integration Guide

gitplugin logo Integration Basics

To learn on how to setup specific git repository with Jira, follow related git host topic on the sidebar. At the end of this guide, the user will be able to grasp how easy it is to integrate git repositories with Git Integration for Jira.

Connecting to a Single Git Repository

This process requires an existing git host repository.

To connect a git repository to the Jira server via the Git add-on:

  1. Jira 7.x Go to Administration > Applications.
    Jira 6.4.x Go to Administration > Add-ons.
    or access it via dashboard Git menu > Manage repositories.
  2. Under Git Integration Plugin for Jira, select Git Repositories.
  3. Click Connect to Git Repository.  The Connect to Git Repository Wizard appears.
  4. Enter repository url on the provided box.  Click Next.
    Initially, the repository URL can be obtained from the repository's project page.
  5. On the Authentication screen, upload or paste the private key in the respective box.  Click Next.
    If the private key requires a password it will be prompted on the screen that follows.
  6. On the Permissions screen, change settings as required or leave the default settings as is.  Click Next.
  7. Click Finish.  The repository is now connected for use with Jira.

Connecting to a Git Host Account via Auto-Connect Recommended

This process requires a git host account (e.g. GitHub/GitLab/VSTS etc.)  Use the auto-connect integration panel in Jira Cloud/Server to connect git repositories from git hosts to Jira.

  1. On your Jira dashboard menu, click Git then Manage repositories.
  2. Click a git host from the auto-connect integration panel.
  3. The Connect Wizard is displayed. Follow screen instructions to import git repositories.
  4. On the following screen, change settings as required or leave the default settings as is.
  5. jira server connect integration settings dialog
    • Jira Server only On the Integration Settings, setting the Require User PAT option to ON will require users to provide PAT which will be used for branch and merge/pull request creation/deletion (via the developer panel on the Jira issue page).  This is a security feature of Git Integration for Jira add-on for git hosts that support two-factor authentication.  This option requires the Repository Browser feature to be enabled.
    • warning
      Do not enable this feature for connected git hosts that don't support it.  For example, TFS2013/2015 does not support PATs.  Users won't be able to create branches or create pull/merge request if the above setting is ON.
    • Jira administrators can configure the Require User PAT setting when connecting a 2FA git host via the Auto-connect integration panel or via Edit integration settings in the Manage repositories page.  If set to ON, Jira Users are required to set their PAT for specific repositories via Repository Browser.  The setup PAT link is accesible via the developer panel on Create Branch or Create Pull/Merge Request dialogs in the Jira issue page.
    • note
      This setting is only available for auto-connected git hosts in Jira Server.
  6. Click Finish to accept the settings and complete the auto-connect setup.

Linking Git Commits to Jira Issue

 

Open a Jira issue then go to the Git Commits tab. In this tab, you will see commits, files changed, links to external repository, commit author and more.

Linking commits to Jira

In the above example, the issue key GIT-913 text is inserted into a git commit message to link the commit to this issue.

The git commit will get associated with the Jira issue if the commit message includes the exact issue ID.  The Git Integration for Jira add-on will automatically index new commits and associate the referenced issue.  For better readability, place the issue key text at the start of the commit message.

Git administrator »

If you want to enforce the commit with a hook, please install this Git commit hook script. Commit-msg Hook open in new tab .

Smart Commits

Smart Commits enable users to perform actions on Jira issues from a single commit.  In a commit message, enter the issue key and some desired action such as resolving an issue, closing an issue, time tracking or all of them.

Smart commits

For example, if a user wants to log specified time with worklog comment, adds a comment, and resolve the issue TEST-100, enter the commit message as follows:

TEST-100 #time 2h 30m Fixed code #comment Merge to master #resolve

Enable/disable this feature via:

  • Connect to Git Repository wizard
  • Connect to Git Repository - Advanced setup
  • Add-ons/Applications > Git Repositories > Edit Repository

To learn more about Smart Commits, see Git Integration for Jira: Smart Commits.

Repository Browser

The Repository Browser permits users to explore the repository similar to browsing a folder in Finder or Windows Explorer.

Go to the Git menu in Jira then select View all repositories (or specific repository if it appears in the Git menu.)

The Repository Browser page is displayed.  Click a repository to view its contents.

Repository Browser

Enable/disable this feature via:

  • Connect to Git Repository wizard
  • Connect to Git Repository - Advanced setup
  • Add-ons/Applications > Git Repositories > Edit Repository

Creating Branches and Pull/Merge Requests

The Git Integration for Jira add-on adds two features on the Jira issue developer panel – Create Branch, and Create Pull/Merge Request.  For more information about the developer panel, see the Git for Jira - Developer Panel documentation icons.

Creating Branches

Open a Jira issue then on the developer panel, click Create Branch to create a branch for the selected repository.  The following dialog is displayed:

Jira Git Source Code panel - create branch
  • Select a Repository.
  • Set Base branch and Branch name
  • The Git add-on will populate the Branch name field according to the Branch Name Template declared in the Git Integration Options icons via General Settings.  Enter a descriptive name or leave it as is (recommended).

This will create the named branch to the target repository in the git host. The newly-created branch is also listed under Branches on the developer panel.

Creating Pull/Merge Requests

Open a Jira issue then on the developer panel, click Create Pull/Merge Request to create a pull/merge request for the selected repository.  The following dialog is displayed:

Jira Git Source Code panel - compare code
  • Select Repository from the list.
  • Choose the newly-created branch as the Source branch.
  • Set master as the Target branch.
  • Enter a descriptive title or leave it as is (recommended).

This will create the named pull/merge request to the target repository in the git host.  The newly-created pull/merge request is also listed under Branches on the developer panel.

Creating Branches and Pull/Merge Request with Request User PAT Jira Server Only

The Require User PAT option in the Integration Settings will require users to provide PAT which will be used for branch and merge/pull request creation/deletion (via the developer panel on the Jira issue page).  This is a security feature of Git Integration for Jira add-on for git hosts that support two-factor authentication.

Access the Create Branch and Create Pull/Merge Request features in the Jira issue developer panel.  For more information, see Git for Jira - Developer Panel icons.