Summary

When adding a linked repository (under Bamboo Administration > Linked repositories) to Bitbucket Cloud from Bamboo, there are 2 options for authenticating the repository on Bitbucket Cloud.

1. Username and password.
2. SSH private key.

For GitHub, authentication can be done using a username and Personal Access token. For more details, refer to the GitHub integration with Bamboo. However, SSH authentication can also be possible for the GitHub repository using the Repository Host as Git type in Bamboo.

This document will explain how to generate a new SSH key-pair and set it up with the option "SSH private key" under "Authentication type" to use the SSH key-pair for authentication of the repository.

Environment

This applies to all supported Bamboo versions and linked repository types with "Bitbucket Cloud".

Solution

A very brief introduction to SSH and key-pair:

• SSH (Secure Shell) is a network protocol, that provides a secure channel over a network for a client and server application to transfer data or information OR a secured way to access any resource over a network.
• In key-based authentication, in order to establish secure ssh connection between 2 systems, we generate 2 keys: one is public key and the other is private key.
• Private and Public keys can be generated by using the command on client system terminal: ssh-keygen -t rsa (Where "t" represents option to specify the type of key where possible values are "rsa","dsa","ed25519" and "ecdsa").
• Above command will generate Private and public key pair which is unique for every user.
• Private key is stored on client or local machine where public key is copied to remote machine.
• Whenever we make connection to remote server using ssh, these 2 keys are checked and if the right combination of private key and public key is found the connection is established.
• The ssh-keygen command generates two keys: 1) id_rsa, which is a private key and will remain on client machine(Bamboo for our case). 2) id_rsa.pub, which is public key and will be copied to remote server(Bitbucket Cloud for our case).

To generate SSH key-pair:

For Linux or macOS:

• Generate a new SSH key-pair using the below command from the terminal:

ssh-keygen -m PEM -t rsa -C "my@email.com"

• By default, the system adds keys to the  directory /Users/<yourname>/.ssh on macOS and  /Users/<username>/.ssh on Linux.
• The command prompts you for a file to save the key in:

$ ssh-keygen -m PEM -t rsa -C "my@email.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/<username>/.ssh/id_rsa):

• Press the Enter or Return key to accept the default location.
• Enter and re-enter a passphrase when prompted. The command creates your default identity with its public and private keys. The whole interaction looks similar to this:

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/<username>/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/<username>/ssh
Your public key has been saved in /Users/<username>/ssh.pub
The key fingerprint is:
SHA256:JiZTBd2qDSJXsYoEs87s6kaCWPdkQ+47m0PlRTdJ8/Q XXXXXXXXXXX
+---[RSA 3072]----+
|o     o+.. .o..  |
| +    oo. o ++ . |
|. .  +o  o . .. E|
|+.o.+o* o .      |
|o=.++*oBS.       |
|=.   +=oo        |
|o.   . .         |
|..    +.         |
|+.    o+         |
+----[SHA256]-----+

• List the contents of ~/.ssh to view the key files. 

  You should see something like the following:

  $ ls ~/.ssh
  id_rsa id_rsa.pub

  The command displays two files, one for the public key (for example id_rsa.pub ) and one for the private key (for example, id_rsa).

For Windows:

• Generate a new SSH key-pair using the below command from the command prompt or Git Bash window: 

$ ssh-keygen -m PEM -t rsa -C "my@email.com"

• By default, the system adds keys for all identities to the /Users/<username>/.ssh directory.
• The command prompts you for a file to save the key in:

$ ssh-keygen -m PEM -t rsa -C "my@email.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/<username>/.ssh/id_rsa):

• Press the Enter to accept the default location.
• Enter and re-enter a passphrase when prompted. The command creates your default identity with its public and private keys. The whole interaction looks similar to this:

Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/<username>/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /c/Users/<username>/ssh
Your public key has been saved in /c/Users/<username>/ssh.pub
The key fingerprint is:
SHA256:JiZTBd2qDSJXsYoEs87s6kaCWPdkQ+47m0PlRTdJ8/Q XXXXXXXXXXX

• List the contents of ~/.ssh to view the key files. You should see something like the following:

  dir .ssh 
  id_rsa  id_rsa.pub

  The command displays two files, one for the public key (for example id_rsa.pub ) and one for the private key (for example, id_rsa).

Once a new SSH key-pair is created:

• The  Private key(for example, id_rsa) needs to be added in Bamboo under Bamboo Administration > Linked Repository >  "Authentication Type" either by "Use shared credentails" or by "Use SSH customer key".
• For the "Use shared credentials" option, shared credentials should be uploaded by creating from Bamboo Administration > Shared credentials option. More info on shared credentials can be found on the  Shared credentials page.
• For "Use SSH Customer key", a private key file can be directly uploaded by clicking on the choose file option.
• For Bitbucket Cloud Repository Type: The generated public key must be added to the Bitbucket Cloud under the repository under access keys for which the linked repository is being created in Bamboo.
• For GitHub repository: Create a repository under Bamboo Overview > Linked Repositories > Add Repository > Select Repository Host as Git. Additionally, add the generated ssh public key to the GitHub account settings > SSH and GPG keys > New SSH key. Refer this GitHub document for more details.
• With this setup, Bamboo can access the repository using the private and public key pair.