Using SSH keys with GitLab CI/CD

GitLab does not have built-in support for managing SSH keys in a build environment (where the GitLab Runner runs).

Use SSH keys when you want to:

• Check out internal submodules.
• Download private packages using your package manager. For example, Bundler.
• Deploy your application to your own server or, for example, Heroku.
• Execute SSH commands from the build environment to a remote server.
• Rsync files from the build environment to a remote server.

The most widely supported method is to inject an SSH key into your build environment by extending your .gitlab-ci.yml, and it’s a solution that works with any type of executor (like Docker or shell, for example).

Create and use an SSH key

To create and use an SSH key in GitLab CI/CD:

1. Generate a new SSH key pair.
2. Add the private key as a file type CI/CD variable named SSH_PRIVATE_KEY.
3. Run ssh-agent in the job, which loads the private key.
4. Copy the public key to the servers you want to have access to (usually in ~/.ssh/authorized_keys). If you are accessing a private GitLab repository, you also need to add the public key as a deploy key.

In the following example, the ssh-add - command does not display the value of $SSH_PRIVATE_KEY in the job log, though it could be exposed if you enable debug logging. You might also want to check the visibility of your pipelines.

Add an SSH key as a file type variable

To add an SSH key to your project, add the key as a file type CI/CD variable:

• Set Visibility to Visible. Any other setting prevents the variable from having multiple lines.
• In the Key field, enter the name of the variable. For example, SSH_PRIVATE_KEY.
• In the Value field, paste the content of the private key. The variable value must end in a newline (LF character). To add a newline, press Enter or Return at the end of the last line of the SSH key before saving it in the CI/CD settings.

Add an SSH key as a regular variable

If you do not want to use a file type CI/CD variable, see the example SSH Project. This method uses a regular CI/CD variable instead of the recommended file type variable.

SSH keys when using the Docker executor

When your CI/CD jobs run inside Docker containers (meaning the environment is contained) and you want to deploy your code in a private server, you need a way to access it. In this case, you can use an SSH key pair.

1. Generate a new SSH key pair. Do not add a passphrase to the SSH key, or the before_script will prompt for it.

2. Add the private key as a file type CI/CD variable named SSH_PRIVATE_KEY.

3. Modify your .gitlab-ci.yml with a before_script action. In the following example, a Debian based image is assumed. Edit to your needs:

   before_script:
     ##
     ## Install ssh-agent if not already installed, it is required by Docker.
     ## (change apt-get to yum if you use an RPM-based image)
     ##
     - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'
   
     ##
     ## Run ssh-agent (inside the build environment)
     ##
     - eval $(ssh-agent -s)
   
     ##
     ## Give the right permissions, otherwise ssh-add will refuse to add files
     ## Add the SSH key stored in SSH_PRIVATE_KEY file type CI/CD variable to the agent store
     ##
     - chmod 400 "$SSH_PRIVATE_KEY"
     - ssh-add "$SSH_PRIVATE_KEY"
   
     ##
     ## Create the SSH directory and give it the right permissions
     ##
     - mkdir -p ~/.ssh
     - chmod 700 ~/.ssh
   
     ##
     ## Optionally, if you will be using any Git commands, set the user name and
     ## and email.
     ##
     # - git config --global user.email "user@example.com"
     # - git config --global user.name "User name"

   The before_script can be set as a default or per-job.

4. Make sure the private server’s SSH host keys are verified.

5. As a final step, add the public key from the one you created in the first step to the services that you want to have an access to from inside the build environment. If you are accessing a private GitLab repository you must add it as a deploy key.

That’s it! You can now have access to private servers or repositories in your build environment.

SSH keys when using the Shell executor

If you are using the Shell executor and not Docker, it is easier to set up an SSH key.

You can generate the SSH key from the machine that GitLab Runner is installed on, and use that key for all projects that are run on this machine.

1. First, sign in to the server that runs your jobs.

2. Then, from the terminal, sign in as the gitlab-runner user:

   sudo su - gitlab-runner

3. Generate a new SSH key pair. Do not add a passphrase to the SSH key, or the before_script will prompt for it.

4. As a final step, add the public key from the one you created earlier to the services that you want to have an access to from inside the build environment. If you are accessing a private GitLab repository you must add it as a deploy key.

After generating the key, try to sign in to the remote server to accept the fingerprint:

ssh example.com

For accessing repositories on GitLab.com, you would use git@gitlab.com.

Verifying the SSH host keys

It is a good practice to check the private server’s own public key to make sure you are not being targeted by a man-in-the-middle attack. If anything suspicious happens, you notice it because the job fails (the SSH connection fails when the public keys don’t match).

To find out the host keys of your server, run the ssh-keyscan command from a trusted network (ideally, from the private server itself):

## Use the domain name
ssh-keyscan example.com

## Or use an IP
ssh-keyscan 10.0.2.2

Add the hosts to your project as a file type CI/CD variable, except:

• Use SSH_KNOWN_HOSTS as the Key.
• Use the output of ssh-keyscan as the Value.

If you must connect to multiple servers, all the server host keys must be collected in the Value of the variable, one key per line.

Now that the SSH_KNOWN_HOSTS variable is created, in addition to the content of .gitlab-ci.yml, you must add:

before_script:
  ##
  ## Assuming you created the SSH_KNOWN_HOSTS file type CI/CD variable:
  ##
  - cp "$SSH_KNOWN_HOSTS" ~/.ssh/known_hosts
  - chmod 644 ~/.ssh/known_hosts

Troubleshooting

Error loading key "/builds/path/SSH_PRIVATE_KEY": error in libcrypto message

This message can be returned if there is a formatting error with the SSH key.

When saving the SSH key as a file type CI/CD variable, the value must end with a newline (LF character). To add a newline, press Enter or Return at the end of the -----END OPENSSH PRIVATE KEY----- line of the SSH key before saving the variable.