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.

note
You cannot delete filesystem-based key using add-on configuration.
FYI
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)
note
The developer’s local system should not have the same private key.

Generating SSH Keys

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

Beanstalk
Github
Bitbucket
Git-scm (Windows)
GitLab
Gitolite
Gerrit

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

GitBlit
Team Foundation Server

The SSH support starts with TFS 2013 and later versions.

note
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  > Add-ons. Click Manage Add-ons on the sidebar. Under Git Integration Plugin for Jira, select SSH Keys.

helpful tip
If using Jira 7, go to Administration  > Add-ons. Select Applications on the page tab. Under Git Integration Plugin for Jira on the sidebar, select SSH Keys.
Add SSH key and associate to repository(ies)
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:

Add SSH key input screen
helpful tip
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.

The following screen is displayed:

Associate SSH key config screen

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.

FYI
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 add-on, 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. Associate existing ssh key to added repository
  5. Select the SSH key that you have associated to the previously added repository from the Existing key list.
  6. 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.

note
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.