Learn basic integration for most git hosts by connecting git repositories to Jira Server via Git Integration for Jira app.

What's on this page:

Connecting to a Git Host Account via Auto-Connect

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. This is the recommended way of integrating your multiple git repositories to Jira.

1. On your Jira dashboard menu, click Git > Manage repositories.

2. Click a git host from Auto-connect integration panel.

Select from the supported git host integration (or click the integration links below to follow to their own integration guide):

Azure DevOps Server / TFS

Gerrit

Git (this page)

3. The Connect Wizard is displayed. Enter login credentials. If two-factor authentication is enabled for your git host, enter the token as the password instead. Follow screen instructions to import git repositories.

4. On the following screen, change settings as required or leave the default settings as is.

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 app for git hosts that support two-factor authentication. This option requires the Repository Browser feature to be enabled.

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 accessible via the developer panel on Create Branch or Create Pull/Merge Request dialogs in the Jira issue page.

This setting is only available for auto-connected git hosts in Jira Server.

For more information on Project permissions and repository associations, see Setting Project Permissions.

5. Click Finish to accept the settings and complete the auto-connect setup.

Connecting to a Single Git Repository

This process requires an existing git host repository.

To connect a git repository to Jira via the Git Integration for Jira app:

1. Go to dashboard menu Git > Manage repositories.

2. Click Connect to Git Repository. The Connect Wizard is displayed.

Enter repository clone URL on the provided box. Initially, the repository URL can be obtained from the repository's project page.
If you want to control the repository connection options, click the Advanced setup label.
Click Next if you want to skip advanced setup and proceed with the standard setup.

3. On the Authentication screen:

If your repository clone URL is an SSH connection, upload or paste the private key in the respective input box and enter other required fields.
For HTTPS/HTTP connections, enter login credentials. If two-factor authentication is enabled for your git host, enter the personal access token as the password instead.

4. Click Next. The Settings dialog appears.

Change settings as required or leave the default settings as it is.

4. Click Finish to complete this setup. The repository is now connected for use with Jira.

Setting Up Web Links

The Git Integration for Jira app automatically configures web links for most git hosts via Auto-connect integration panel. Manual configuration of web links is optional.

Linking Git Commits to Jira Issue

Right click here and view the video in a new browser tab.

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.

In the above example, the issue key GIT-924 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.

Only the commits that are linked to Jira issues will show on the Jira Activity Stream (not all commits in repositories).

Git administrator »

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

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.

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.

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 app 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 ».

Default Branch

Most git integrations allow changing of the default branch of the repository/project other than "master". This change is reflected in the Repository Settings of the Git Integration for Jira app on the next reindex. Auto-connected integrations support this feature where Git Integration for Jira app gets the default branch from almost all integrations and apply this setting at repository level. For the case with Gerrit, the default main branch is always “master”.

Main branch for repositories within an integration can only be changed on the git server.

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:

Select a Repository.
Set Base branch and Branch name
The Git Integration app will populate the Branch name field according to the Branch Name Template declared in the Git Integration Options » 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:

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

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 ».

Integration Basics