SSH Git deploy keys with Linux servers and Bitbucket

There's a couple of ways to push code to production. Most larger projects have their own release flow, some of which includes automation, tests, etc. In this case I'm talking about a lot smaller projects.

So this is how to simply set up your server so you can pull code from bitbucket without using your own personal bitbucket account password via https, but instead pull the code with a server specific deploy key over ssh.

First you need to generate your server specific SSH-key, you can use the same key for multiple servers, but from a security perspective it's better to have unique keys for each server.

Setting up the server with SSH keys

To generate the key we use the command ssh-keygen -t rsa, you'll be asked a couple of questions, like where to store the key (just go with the default if you're unsure) and if you want to protect your key with an additional password.

 bha@prod-01:~# ssh-keygen -t rsa 
 Generating public/private rsa key pair. 
 Enter file in which to save the key (/home/bha/.ssh/id\_rsa): 
 Enter passphrase (empty for no passphrase): 
 Enter same passphrase again: 
 Your identification has been saved in /home/bha/.ssh/id_rsa. Your public key has been saved in /home/bha/.ssh/id\_rsa.pub. 
 The key fingerprint is: SHA256:HgrzdwgjYefhZAF0auqVXBZ7HSNLzZ+6fXjmR5nL09A 
 bha@prod-01 The key's randomart image is: 
 +---\[RSA 2048\]----+ 
 | .o.+ ooo       | 
 | o = +oo        | 
 | = O o .. .     | 
 | = @ o o        | 
 | . B = S . .o   | 
 | . . = = o. .oE | 
 | . o + .o ..oo  | 
 | . .. o ++o     | 
 | =...           | 
 +----\[SHA256\]-----+ 

If you went with the default location, your keys will be saved in the .ssh directory in your home folder. Inside of this folder you'll find at least two files, the id_rsa and id_rsa.pub.

The file id_rsa is your private key, do not under any circumstance share this key to anyone. Whilst the file id_rsa.pub is your public key, you can share this to your heart's content, it doesn't matter.

 bha@prod-01:~# ls -la ~/.ssh 
 total 20 
 drwx------ 2 bha bha 4096 feb 17 18:09 . 
 drwx------ 3 bha bha 4096 feb 17 18:06 .. 
 -rw------- 1 bha bha 400 feb 17 18:06 authorized_keys 
 -rw------- 1 bha bha 1675 feb 17 18:09 id_rsa 
 -rw-r--r-- 1 bha bha 394 feb 17 18:09 id_rsa.pub 

That's it! You've now created you SSH key pair!

Setting up Bitbucket to use SSH access keys

Log on to bitbucket and navigate to your project. Go to Settings -> Access keys (not to be confused with SSH keys under pipeline!).

In this view you'll see all access keys that have been added to this specific project.

BitBucket Repository Access Keys View

To add your newly created key from your server, you'll need to copy the contents of id_rsa.pub (your public key). SSH keys are not binary, so you'll be able to just output the contents and copy it to your clipboard.

 bha@prod-01:~# cat ~/.ssh/id_rsa.pub 
 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCvEzvmLseLTHYFWUeMMrwatA2c913lEXOKBWIjPwZxb8A2jEWkzREoCOAxgSF2ZkV5AJaY/QQ68WuUtkSegIfQF9LSDq51BhrFyi65eBPpNneLpI5bs70eSFN2KyKaSdDW79flyj28g4U94JA+pIRw2XPDwKrPr6NmvaPcGIIL5MWxgNKX40bGX3NpnyyJSG4LRkdoj4tF5Z6ZuglALXVTjrjopeBX0SRPlnHmtcJhYFIpzgPgXenFtzdLTNsXnhssGtNgajRW8D2oDUiO+MIaWeH+AZjhCqk+rbQSOz1QKvBsPN5WNcf0fso/82V1b2ymgjLzj/Ci1HTJ4rAQHaGN bha@prod-01 

Back at the browser, click the button "Add key". A dialog window will appear, this is where you should paste in the contents from the public key.

BitBucket Repository Add SSH Key View

And finally click the "Add key" button in the dialog to save the key.

Adding a new project over SSH

You can now clone your project with nothing but the ssh url to the repository.

(If it's the first time you ssh to bitbucket it might ask you to check the authenticity of the host for bitbucket; if it looks correct continue with yes)

 bha@prod-01:~/my-repo# git clone git@bitbucket.org:yourusername/your-repository.git .
  Cloning into '.'... 
  The authenticity of host 'bitbucket.org (104.192.143.3)' can't be established. RSA key fingerprint is SHA256:zzXQOXSRBEiUtuE8AikJYKwbHaxvSc0ojez9YXaGp1A. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'bitbucket.org,104.192.143.3' (RSA) to the list of known hosts. 
  remote: Counting objects: 3, done. remote: Compressing objects: 100% (2/2), done. 
  remote: Total 3 (delta 0), reused 0 (delta 0) 
  Receiving objects: 100% (3/3), done. 

Updating an old project from https to SSH

If you've already got a project checked out via https, you can easily update the remote url.

First check that your project uses the https endpoint with git remote -v

 bha@prod-01:~/my-repo# git remote -v 
 origin https://yourusername@bitbucket.org/yourusername/your-repository.git (fetch) 
 origin https://yourusername@bitbucket.org/yourusername/your-repository.git (push) 

As in our example, both the push and fetch urls are over https. To update them we can change the origin with git remote set-url.

 bha@prod-01:~/my-repo# git remote set-url origin git@bitbucket.org:yourusername/your-repository.git 

We should be able to double check that origin was updated correctly via the git remote -v command.

 bha@prod-01:~/my-repo# git remote -v 
 origin git@bitbucket.org:yourusername/your-repository.git (fetch) 
 origin git@bitbucket.org:yourusername/your-repository.git (push) 

Congratulations! You should now be able to git pull without giving you personal bitbucket account password.

Benjamin Horn
Benjamin Horn
Developer at Bazooka
A Finnish-German full-stack developer who's worked with a multitude of different technologies throughout the years.
Vaasa, Finland