March 28th 1 PM ET
Free Workshop: Escape the chaos of context-switching

Git Integration for Jira Self-Managed (Data Center/Server) Documentation

Working with SSH keys

SSH keys are required in order to provide secure connection with the remote git host. The Git Integration for Jira app uses one set of keys for accessing all configured repositories.

VERSION 4.0+
OpenSSH is now fully supported.

Follow this guide if you are one of the users who are limited to or wanted to use SSH to securely connect to your git repositories.

Introduction

There are two options available for specifying SSH keys:

  • SSH keys stored on server filesystem. The keys are located in the home folder of the user which account is used to run Jira. This option provides better compatibility with installation of the previous versions of the Git Integration app. This option does not support passphrases.

  • SSH keys are stored in the app configuration. The keys are added using the Git Integration app configuration. This option supports passphrases.

Features such as branch and pull/merge request creation is only available to repositories/git hosts that were connected via the Auto-connect integration.

Jira Data Center
In case of Jira DC with multiple nodes, the SSH keys stored on server filesystem must be the same on all nodes.

 

Getting started

Before connecting repositories via SSH, users are required to generate SSH keys for use with the remote git host (public key) and for Git Integration app in Jira (private key).

Generated SSH keys always come in pair. (Example: id_rsa.pub and id_rsa)

For establishing safety connection with SSH, upload a public key to the SSH server and set the private key to the SSH client.

In this case, the SSH server is the Git server and the SSH client is the Jira server. Therefore:

  • Git server — public key

  • Jira server — private key (Git Integration for Jira sidebar ➜ SSH Keys)

The developer’s local system should not have the same private key.

Note that Git Integration for Jira app SSH key:

  • VERSION 4.0+ now fully supports OpenSSH format.
  • must be the private key.
  • must use the supported certificate format: RSA.
  • must use the supported storage format: OpenSSL PEM.
  • For more information, see troubleshooting article SSH key format is invalid.

 

Windows

For Windows, we recommend to use PuTTY and use PuTTYgen to generate public and private SSH keys.

  1. Launch PuTTYgen and refer to the above image for the rest of the steps on this section.

  2. Set Type of key to generate to RSA.

  3. Set Number of bits in a generated key to 4096.

  4. Click Generate.

  5. Follow screen instructions such as moving your mouse pointer on random locations on the blank area of the PuTTYgen dialog. Do this until the progress bar completely fills up and the SSH key pair is generated.

  6. Entering a Passphrase for the generated key is optional but will ensure a more secure connection.

  7. Save your generated public and private key to a file by clicking the respective options.

  8. Copy the generated key. This is the public key that you will be using on the SSH configuration page of your git host.

  9. For the private key, see the note below.

PuTTY creates a private key in its own “.ppk” format. To convert it to “.pem”, the user should do the Conversions ➜ Export OpenSSH key menu option in PuTTYgen. Add/upload this file to Git Integration for Jira app ➜ SSH keys or when prompted on connecting SSH git repositories in Jira via Connect Git Repository wizard.

You can also use the git bash command line to generate SSH key pair. For detailed information, see Generate SSH via Git bash.

Read on the section Generating SSH keys and follow specific information for the git host and platform that you use.

 

Linux/MacOS

On Linux and MacOS, this generates an SSH key in RSA format:

ssh-keygen -t rsa -b 4096 -m pem -C "[email protected]"

MacOS often incorrectly creates an OpenSSH format certificate. For more details, see information on this common problem.

 


Prev: Getting started for Git administrators

Next: Genenerating SSH keys

 

More on Working with SSH keys

Generating SSH keys

Adding a private SSH key

Adding a public SSH Key

SSH keys configuration

Adding and associating SSH keys

Removing SSH keys

Reconfigure Git repositories and SSH keys

Have feedback about this article? Did we miss something? Let us know!
On this page