Git Integration for Jira Integration

In this page

What is Git Integration?

(supported since Better Excel Exporter 5.3.0)

Git Integration is the most advanced Jira app to integrate the Git version control system with the Jira platform. It supports all major Git servers, including Git itself, GitHub, GitLab, BitBucket, Microsoft Azure DevOps Repos, AWS CodeCommit and Gerrit.

Git Integration integration features

• You can export the Git commits associated with Jira issues, including the following information for each commit:
  • repository name
  • branch names
  • commit ID (hash)
  • commit author
  • commit date and time
  • commit message
  • commit notes
  • changed files and statistics (number of added, modified and deleted lines)
• You can export the Git Integration specific custom field types like gitBranch and gitCommitsReferenced to Excel.
• You can use the git-report.xlsx template to generate the following Excel reports:
  • commit count per issue
  • code changes (lines added and deleted) per issue
  • commit count per author
  • commit activity per repository (timeline per year and week)
  • author activity (timeline per year and week)
  • ... plus your custom Excel reports from Git data!

(Need more features? Tell us in a support ticket!)

Tutorial video

The Better Excel Exporter app can export issues with the linked Git commits to customizable Excel reports:

Git Integration Excel export samples

Configuration

Configuring the Git Integration Excel views

Note that the Git Integration custom fields will be available in every Excel view. There are additional views that are specific to Git Integration and are disabled by default. Don't forget to activate those!

Steps:

1. Login to Jira as administrator.
2. Go to Administration → Add-ons → Excel Views (under Better Excel Exporter).
3. Click the view Git Report (Excel).
4. Check the contexts (screens) in which you want this integration be available. (If unsure, check Issue Navigator at least.)
5. Click Save.

Configuring the Git Integration custom fields

There is nothing to do. Better Excel Exporter will automatically recognize the Git Integration managed fields and export them accordingly.

Configuring the Git Integration Excel report templates

There is a couple of configuration options for the git-report.xlsx template.

The reports in this template use Git commits as source data, but they ignore merge commits, by default. For example, commit counts exclude merge commits, because we think those are not the same type of contribution as "regular" commits which introduce actual changes to the code. If you want to include merge commits, change this in the A2 cell of the template:

<jt:forEach items="${gitIntegration.getRepeatingCommits(issues)}" var="entry" where="${!entry.value.mergeCommit}">${entry.key.key}

to this (basically remove the "where" condition that filtered out merge commits):

<jt:forEach items="${gitIntegration.getRepeatingCommits(issues)}" var="entry">${entry.key.key}

Also, if you generate these reports for a very large number of issues or for a very large number of commits, don't forget that this template is also subject to certain data limits (like any other template):

1. the number of issues is limited (configuration how-to)
2. the number of commit per issue is limited (configuration how-to)

Finally, please note that in Git the same commit can appear on multiple branches, e.g. on "master" and on "feature/x" after "feature/x" was merged to "master". In this case, that commit is counted twice in the reports! If you find this confusing, you can narrow down the reports to a single (or more) branch by using the "Branch" drop-down in the top.

Limiting the exported Git commits

By default, only the last 1000 commits are exported for each issue, to avoid unexpected load and memory consumption during the Excel export. It can be configured via this variable in the git-integration-tool.groovy script:

/**
 * Upper limit for the commits to export per issue.
 */
def MAX_COMMITS = 1000

Configuring the Git Integration REST API access

As this integration relies on the Git Integration REST API, you need to configure the login credentials of a valid Jira user account for the REST API calls in the templates:

1. Go to Administration → Add-ons → Excel Templates (under Better Excel Exporter).
2. Open the git-integration-tool.groovy template for editing, and set the username and password to these configuration variables in the top part (don't remove the quotation marks around the string!):

   // git-integration-tool.groovy
   
   /* Git Integration REST API request parameters. */
   def restUserName = "admin"
   def restPassword = "admin"
   

3. Save the changes. (Don't worry about storing passwords here: this file is visible only for Jira administrators, who would have super-user permissions anyway.)

Notes:

• It is safer to avoid usernames and passwords that contain non-English characters. Albeit our Git Integration script correctly encodes international usernames and passwords, their handling also depends on the configuration of the container that hosts your Jira web application (typically Tomcat). If you're having difficulties, just replace those characters in your username or password with English letters or numbers.
• Similarly, it is safer to avoid usernames and password that contain special characters (most typically "#" and "$"). These are special control characters in Groovy strings. If you can't avoid those, escape the characters according to the language rules.

Finally, the following section describes a confusing situation when all REST API calls result in "Server returned HTTP response code: 403" or "401" errors. If you are not affected, you can skip this section.

Why does this happen? As its default behavior, Jira will lock your account and present a CAPTCHA on the login form after a few unsuccessful login attempts. Since the Git Integration integration may send several REST API requests per export, all using the same username and password, the unsuccessful login attempts limit can be reached very quickly if the password is wrong.

How to fix it? You just have to pass the CAPTHCA verification, that's it. First off, be 101% sure that the REST username and password are correct. If those are, but you are still receiving 403's, please open Jira in your browser, logout and login with the same user account which you configured for the REST calls. You will be asked for a CAPTCHA verification, but after answering that and logging in to Jira, the REST calls will also be successfully executed!

Please note that it will never happen again, unless you change the password of the corresponding Jira user account.

If you are an administrator, there is also a quicker solution: go to Administration → User management and clear the failed login attempts counter with one click. Or, you can increase the allowed login attempts or even disable this feature altogether in Jira.

Troubleshooting

Branch names are not exported with pre-3.6.0 Git Integration versions

Exporting the Git commits relies on the /rest/gitplugin/1.0/issues/{issueKey}/commits endpoint provided by the Git Integration REST API. This endpoint returns the branch names since Git Integration 3.6.0. Therefore, Better Excel Exporter exports the branch names only with Git Integration 3.6.0 or newer versions.

Learn more about Git Integration

• Git Integration product information (at its own vendor)
• Git Integration documentation
• Git Integration app page (on the Atlassian Marketplace)