Git Integration for Jira Integration

In this page

What is Git Integration?

(supported since Better PDF Exporter 8.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 PDF.

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

Tutorial video

The Better PDF Exporter app can export issues with the linked Git commits to customizable PDF documents:

Git Integration PDF export samples

Configuration

Configuring the Git Integration custom fields

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

Configuring the Git Integration PDF templates

There are new configuration parameters in the top part of the issue-fo.vm template, to enable exporting the Git commits and to select whether the change files and statistics should also be exported (or only the commit author, ID, date, etc.):

#set($exportGitIntegrationCommits = $pdfView.name.contains('Git')) ## set to "true" to export commits
#set($exportGitIntegrationChangeFiles = true) ## set to "true" to export Git change files

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 PDF 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 → PDF Templates (under Better PDF Exporter).
2. Open the issue-fo.vm 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!):

   ## issue-fo.vm
   
   ## Jira user credentials for REST API calls
   #set($restUserName = "admin") ## Jira username for REST authentication
   #set($restPassword = "admin") ## Jira password for REST authentication
   

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:

• If you are using multiple REST API based integrations in the same template (ex: Git Integration, Gliffy, Zephyr Squad), then all REST API calls will use with the same user credentials.
• 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 Velocity 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 PDF 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)