Working with SSH Keys

Documentation

Working with SSH Keys

SSH keys are required in order to provide secure connection with the remote git host specified in the Repository Origin field which can be accessed via Connect to Git Repository or in Edit repository/integration settings. The Git Integration for Jira app uses one set of keys for accessing all configured repositories.

Follow this guide if you are one of the users who wre 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.

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 > SSH Keys)

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

Note that Git Integration for Jira app SSH keys:

must not be created using the 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 issue SSH key format is invalid.

Windows

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

Launch PuTTYgen and refer to the above image for the rest of the steps on this section.
Set Type of key to generate to RSA.
Set Number of bits in a generated key to 4096.
Click Generate.
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.
Entering a Passphrase for the generated key is optional but will ensure a more secure connection.
Save your generated public and private key to a file by clicking the respective options.
Copy the generated key. This is the public key that you will be using on the SSH configuration page of your git host.
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.

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 "your_email@example.com

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

Generating SSH Keys

Beanstalk

For MacOS, see Working with Git on MacOS
For Windows, see Working with Git on Windows.
For Linux, see Working with Git on Linux.

Bitbucket

For MacOS/Linux, see Setting up SSH for Git on MacOS/Linux.
For Windows, see Installing or Upgrading Git - Step 1 then Set up SSH for Git.

Gerrit

By v2.6.1 of the Git Integration for Jira app, the Gerrit web linking support is added.

For information about Gerrit software, see Gerrit Software Wiki and Gerrit at Code Review.
For general reference and installation, see Gerrit documentation. Ubuntu installation and fixing registration error.
For information on SSH on Gerrit, see SSH and Gerrit.
For details on User Change-Ids, see Change-Ids in Gerrit.

GitBlit

For information about Gitblit, see GitBlit.
For general reference and installation, see GitBlit Configuration, Using HTTP/HTTPS Transport and Built-in Authentication.
For information on SSH on GitBlit, see GitBlit: Using the SSH Transport.
For GitBlit related FAQ, see GitBlit Frequently Asked Questions.

GitHub

For MacOS, see Generating SSH Keys on MacOS.
For Windows, see Generating SSH Keys on Windows.
For Linux, see Generating SSH Keys on Linux.

GitLab

See reference, Installing Git for MacOS/Windows/Linux.
For creating SSH keys, see Generating SSH Public Key. Also see the video demonstration here.

GitLab CE/EE

Follow the above GitLab references for GitLab CE/EE. Then verify that your GitLab server should have the following SSH settings:

Enabled Git access protocols -- Both SSH and HTTP(s)
RSA SSH keys -- Are allowed

Other SSH key formats may be supported by Git Integration for Jira app, but prefer to use RSA format for your SSH git connections.

Git-scm

See reference, Installing Git for MacOS/Windows/Linux.
For creating SSH keys, see Connecting to GitHub with SSH.

Gitolite

For full reference and installation, see All About Gitolite.
For information on SSH on Gitolite, see SSH and Gitolite.
For details on user key management, see Managing User Keys in Gitolite.

VSTS/TFS/Azure DevOps/Azure Repos

The SSH support starts with TFS 2013 and later versions.

For information about TFS/Azure DevOps Server, see MS Team Foundaton Server.
For general reference and terms, see Git Experience Futures.

For generating SSH keys for Azure Repos (which is applicable to MS git hosts), follow instructions at Use SSH Key Authentication.

Users can use HTTPS or SSH to securely connect to git repositories. HTTPS connections will require the user's login credentials, while SSH connections will require SSH keys.

Adding a Private SSH Key (Jira Server)

From your Jira dashboard menu, go to Git > Manage (Git) repositories. On the sidebar under Git Integration for Jira, select SSH Keys.
Alternatively, go to Jira Administration > Applications. On the sidebar under Git Integration for Jira, select SSH Keys.

Click Add SSH Key. The following screen is displayed.

Utilize the following options for adding the new SSH key:

Option	Description
Key name	Enter a meaningful name for this private SSH key as required.
Private key	This is the actual private SSH key. Upload the private key file via Browse... or paste the generated private key into the provided field.
Passphrase	Optional. Enter the passphrase that was assigned to this private key.

Click Add to complate this setup.

Adding an SSH Public Key

Add a public SSH key to your remote git host to prepare its repositories for connection with the Git Integration for Jira app.

Login to your remote git host.
Go to the SSH configuration page, if supported.
Paste the public key to the provided box and complete the setup.

SSH Keys Configuration (Jira Server)

Manage and associate SSH keys to connected git repositories via the SSH Keys in Git Integration for Jira Server app repository configuration page.

SSH keys configuration in Git Integration app

The list of added private SSH keys is accessible on this page. Both types of SSH keys are displayed in this list. Legacy filesystem-based keys contain directory path in the Private key column.

Refer to the following table for list column information:

Option	Description
Name	The name of the private SSH key will appear here.
Private key	This is the private SSH key in hex mode.
Passphrase	A lock icon is displayed if the SSH key pair has a passphrase.
Associations	Lists the repositories that are associated with this SSH key.
Last used by	Lists the repositories that are using this SSH key.
Operations	Click the icon to perform Delete or Associations functions.

You cannot delete filesystem-based keysfilesy using the Git Integration app configuration.

The SSH keys are also automatically added to this list when adding new repositories that require SSH keys.

Adding and Associating SSH Keys

Limit the usage of the SSH key by associating them to selected repositories. As of v2.6.9 of the Git Integration for Jira app, the option to strictly map keys to repositories is available.

On the SSH Keys page, click Actions > Associations for the selected SSH key.

The following screen is displayed:

Mark the required repository or repositories to associate the SSH key.

Clicking the Select All text label marks all repositories that will be associated to this SSH key.

Clicking the Select None text label deselects all repositores.

Click Save to save the settings.

If an SSH key is strictly associated with some repository, that SSH key is an associated key.

If you have multiple repositories that uses the same SSH key, configure them via Git Integration app by doing the following steps:

Configure a repository that requires an SSH key via Add Repository Wizard.
Associate that SSH key with the currently configured repository via SSH Keys.
Add another repository that requires the same SSH key. You will be presented with the following screen:
Select the SSH key that you have associated to the previously added repository from the Existing key list.
Click Next to continue. Complete the wizard and add another repository as desired.

For third-party products or services (such as GitHub, GitLab, Bitbucket, etc.), register the PUBLIC KEY for target repository or in profile settings of your git account.

For custom git hosting servers, ask your administrator to check that the target keypair's PUBLIC KEY is added into the authorized_keys file of the git server. For more information, see the following article.

Removing SSH Keys

SSH keys cannot be modified or updated. To change the keys, remove and add them again.

If the key is deleted, all repository references will also be removed. Repositories that don't have the key associated to them will use the common keys by default.

Reconfigure Git Repository and SSH Key

Perform the following steps to reconfigure repositories and SSH key:

Remove any old SSH keys configured with the Git Integration app via <JiraHOSTNAME> /secure/ViewSshKeys.jspa
Restart Jira.
Get the following file from your Jira server to your Windows workstation: /home/jira/.ssh/id_rsa
Set up the git repository in Jira using the repository location and upload the private key that was downloaded above.

For multiple repository configuration, see Bulk change.

Connecting SSH Git Repositories (Jira Cloud)

SSH git repositories can be integrated with Jira Cloud via Git Integration for Jira app.

Generate an SSH key pair. We recommend to generate a 4096-bit key.
Obtain the Clone SSH git URL from your git host repository page.
On your Jira Cloud dashboard, go to menu Git > Manage Git repositories.
On the Auto-connect integration panel, click Git.
Paste the clone URL into the Remote Git URL field.
Click Next.
Click Connect.
Paste the Private SSH key on the provided box or click Upload Key File to upload a private SSH key file.
Enter the Passphrase of the private SSH key, if any. Otherwise, leave it blank.
Click Connect.

The connected repository is listed in the git configuration page.

For Jira Cloud integration, we recommend to use the Auto-connect integration panel for connecting git repositories. It supports multiple git repository connections and provides additional features that are not present in SSH integration.

Products

Git Integration for Jira Cloud Git Integration for Jira Server Git Integration for Jira Data Center