« Table of Contents

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.  The git add-on uses one set of keys for accessing all configured repositories.

There are two options available for specifying SSH keys:

  • SSH keys stored on server filesystem 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 add-on. This option does not support passphrases.
  • SSH keys are stored in the add-on configuration. Keys are added using the add-on configuration.  This option supports passphrases.

List of SSH Keys

Both types of SSH keys are displayed on the SSH Keys tab.  Legacy filesystem-based keys contain directory path in the Private key column.

You cannot delete filesystem-based key using add-on configuration.
The SSH keys are also automatically added to this list when adding new repositories that require SSH keys.

Public Key and Private Key with SSH

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.

Take note that the SSH server is the Git server and the SSH client is the Jira server.

  • Git server  —  Public Key
  • Jira server — Private Key (Git Integration Plugin for Jira > SSH Keys)
The developer’s local system should not have the same private key.

For OSX/MacOS, this generates an SSH key on Mac in RSA format:

ssh-keygen -t rsa -b 4096 -m pem  -C "your_email@example.com"

Generating SSH Keys

Configure and generate SSH keys for the following git hosting systems by following the reference links on each sub-section:

Git-scm (Windows)

By v2.6.1 of the Git add-on, the Gerrit web linking support is added.

Team Foundation Server

The SSH support starts with TFS 2013 and later versions.

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 an SSH Key


Go to cog Administration  > Applications. On the sidebar under Git Integration for Jira, select SSH Keys.

Alternatively, from your Jira dashboard Git menu, select Manage repositories. On the sidebar under Git Integration for Jira, select SSH Keys.
Column Description
Name Name of the added SSH key
Private key This is the SSH key in hex mode.
Passphrase Defines true if the SSH key has a passphrase.
Associations Lists the associated repositories with this SSH key.
Last Used By Defines the repository that is using this SSH key.
Operations Click the icon to perform Delete and Associations functions.

Click Add SSH Key to configure the SSH key. The following screen is displayed:

You can upload the private key file via Browse... or paste the key into the Private key field.

Utilize the following options for the new SSH key:

Option Description
Name Enter a meaningful name for this private SSH key.
Private key This is the actual private SSH key.
Paste private key from clipboard or load from a private key file.
Passphrase Optional.  Enter the passphrase that you have assigned to this private key.

Associating an SSH Key to a Repository

Limit the usage of the SSH key only to the selected repositories.  As of v2.6.9 of the Git add-on, the option to strictly map keys to repositories is available.

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

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 that you want to connect with the Git Integration app, you need to:

  1. Configure a repository that requires an SSH key via Add Repository Wizard.
  2. Associate that SSH key with currently configured repository via SSH Keys.
  3. Add another repository that requires the same SSH key.  You will be presented with the following screen:
  4. Select the SSH key that you have associated to the previously added repository from the Existing key list.
  5. 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: https://git-scm.com/book/it/v2/Git-on-the-Server-Setting-Up-the-Server.

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:

  1. Remove any old SSH keys configured with the Git add-on via <JiraHOSTNAME> /secure/ViewSshKeys.jspa
  2. Restart Jira.
  3. Get the following file from your Jira server to your Windows workstation: /home/jira/.ssh/id_rsa
  4. 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.


« Table of Contents