How to set up SSH keys for automatic deployments

Goal

Automatic deployments means to have one repository (usually your code repository) that automatically pushes updates (the results from a CI - pipeline in form of blog-posts) into another repository (pages repository). This is done best with SSH Keys .

You can set up a SSH key on your local computer to connect to GitLab. This enables you to push and pull your (one) repository without the need to authenticate with a password. We highly recommend this.
Please refer to the respective user guide of your GitLab instance, as the workflow is a bit different for this.

Generating a new SSH key pair

Make sure openssh is installed on the machine you are going to generate the keys.

Generating RSA key pair (public + private)

ssh-keygen -t rsa -b 4096 -C "<YOUR-EMAIL-ADDRESS>"
  1. You will be prompted to select a path to save your SSH key pair to. If you don’t already have an SSH key pair in the default path, use the suggested path by pressing Enter.
  2. Then you will be prompted to enter a passphrase to secure your new SSH key pair, but because we want the deployment to happen automatically (no user interaction) the passphrase will be left blank (by pressing Enter twice).

Storing GitLab’s key pair

Now that the keys are generated we also need to save the key pair of the GitLab _ host. To do that enter the following command. This way, when the stateless Docker image is trying to contact GitLab via SSH it won’t be asked for user confirmation.

Inserting GitLab’s key-pair to trust list

ssh-keyscan -H git.rwth-aachen.de >> ~/.ssh/known_hosts

If the GitLab instance is hosted somewhere else, just change the ‘git.rwth-aachen.de’ to the correct host name. Also, here we append the key pair in the known_hosts file but it could be stored in a file with a different name and/or path.

Transferring those values at GitLab

Right now the key pair is saved on your local machine, but a job (usually in the deployment stage) of the pipeline will need them in order to automate the update of the Pages repository and publish a new version of the web site. So we have to transfer those keys in a safe location. Open the Project repository and go to Settings-> CI/CD and expand the Variables section. Then create 3 variables, one for the publickey, one for the private and one for the known_hosts.

Type should be Variable, for Key some descriptive string and in the Value paste the contents of the cat command. Now those 3 variables are saved in secret and are available in the pipeline as environment variables.

The easiest way to get the values is to run the command:

Display the contents of the files

cat ~/.ssh/id_rsa
 
cat ~/.ssh/id_rsa.pub
 
cat ~/.ssh/known_hosts

where .ssh is the folder that contains the key pair, plus the known_hosts file. But xclip can also be used if available.

Copying the contents of the files with xclip

xclip -sel clip < ~/.ssh/id_rsa
xclip -sel clip < ~/.ssh/id_rsa.pub
xclip -sel clip < ~/.ssh/known_hosts

Variables

These variables are saved on the Project repository and not on the Pages repository.

Enable deployments on the Pages repository

Now we need to enable read and write access to the Pages repository, because it is a private repository and only authorized users can access it. To do that, go to the Pages repository → Settings → Repository and expand the Deploy Keys section. Here just write a Title and paste the public key of the pair created before (id_rsa.pub).

Important: Click on the checkbox ‘Write access allowed’.

DeployKey

Project repository is ready to pull and push changes from the Pages repository and this is taken care in the .gitlab-ci.yml file where those environment variables are exported back to default files and the rights are changed so they can be accessed.

See also