Private Git Repositories: Part 2A – Repository SSH Keys

In the first post of this series about using private Git repositories with OpenShift, we looked at the different types of protocols that can be used when accessing a Git repository. We also looked at how these combined with different credential types to control access to a private Git repository.

The preferred mechanism for accessing a private Git repository when using OpenShift is to create a unique repository SSH key. In this blog post, we will look at how to create such an SSH key, configure the GitHub hosting service to use it, and then how to have OpenShift use that SSH key when accessing the repository.

Creating a Repository SSH Key

On UNIX systems, to create an SSH key you can use the ssh-keygen command.

We want to create a unique SSH key to be used just by OpenShift to access the private Git repository. We do not want to use the SSH key as a primary identity key, nor do we want to use an existing primary identity key. This is because it will be necessary to upload the private key of the SSH key pair to OpenShift.

When running ssh-keygen we, therefore, ensure we specify that the generated key should be saved as a separate set of key pair files using the -f option. The generated key should also not have a passphrase, so supply the -N '' option so a passphrase is not requested.

$ ssh-keygen -C "openshift-source-builder/repo@github" -f repo-at-github -N ''

The output from running the command should be similar to the following:

Generating public/private rsa key pair.
Your identification has been saved in repo-at-github.
Your public key has been saved in
The key fingerprint is:
SHA256:z1tdP5Py+LAy7qOS2Zt5OCz0IADlvZPLThDlANPdzLs openshift-source-builder/repo@github
The key's randomart image is:
+---[RSA 2048]----+
| o+o..+          |
| .o.=. +         |
|  .o o  .        |
|   .. o.         |
|   ..+  S       .|
|    o.oE o   . .o|
|     +o B + .o.+.|
|    o  = *oB  * o|
|     .  o=Oo+o.o |

When an SSH key is generated, it is actually a pair of files. The first file is the public key file. In this case, this was called

The public key file is what we need to upload to GitHub and associate with the private Git repository.

The second file is the private key file. This was called repo-at-github.

The private key file is what we need to pass to OpenShift so that it will be able to access the private Git repository to pull down the source code.

Adding the Public Key to GitHub

To upload the public key file to GitHub, we need to visit the GitHub web console for our private Git repository.

On GitHub the term they use to refer to a repository SSH key is a Deploy key.

Visit the Settings page for the repository, and then click on Deploy keys.

Click on Add deploy key and enter a name for the repository SSH key as the Title field, and copy the contents of the public key file into the Key field. The public key file has the .pub extension, in our example

Leave the Allow write access option unchecked, as we only want to provide read-only access to the Git repository using this key. This ensures that even if someone has access to the private key, they will not be able to make modifications to any files hosted by the Git repository.

Press Add key and the public key file will be registered.

Registering the Private Key with OpenShift

Before we can deploy to OpenShift an application from the private Git repository, we need to register the private key with OpenShift.

To do this from the web console, go to Resources->Secrets.

This will bring up a list of existing secrets defined for the project.

Click on the Create Secret button in the top right corner. This will bring up a form to enter in the details of the secret corresponding to the SSH private key.

On this form you need to set the following:

  • Ensure that the Secret Type is Source Secret.
  • Set the Secret Name. In this case, we are using repo-at-github.
  • Ensure that the Authentication Type is SSH Key.
  • Upload or paste in the contents of the private key file. This is the file without the .pub extension. In this case, the repo-at-github file.
  • Enable the Link secret to a service account option.
  • Ensure that the Service Account is set to builder.

The builder service account which the secret was linked to, is the internal user that the platform will use to build your code. It is necessary to link the secret to the service account so that it has permission to use it.

Click on Create to create the secret.

Creating an Application from the Repository

We are now ready to deploy an application using a Source-to-Image (S2I) builder. For this example we are going to use the HTTPD S2I builder.

Selecting this S2I builder from the catalog browser, we are presented with the form to provide the details for the deployment.

We fill this out with the Name for our application, and the Git Repository URL. Because we are going to rely on a repository SSH key for accessing the private Git repository, we need to make sure we use the SSH URI for the Git repository from GitHub.

Before selecting Create for the application, we first need to update settings in the advanced options. Select that link to display the advanced options settings. Find the Source Secret settings and select the secret repo-at-github that we created earlier.

For the purpose of this blog post we created the secret as a first step and then selected it as the Source Secret. If desired, one could have skipped the separate step of creating the secret, and created it direct from the advanced options page by selecting Create New Secret below the Source Secret drop down menu. This would result in a popup window into which you could enter the details of the secret.

In that case, an option to link the secret to the builder service account would not be presented, as OpenShift will know that since it is being added when using a S2I builder, that it should do that step automatically.

Having selected the Source Secret, click on the Create button and the application will be built and then deployed, with the source code being able to be pulled down from the private Git repository over SSH using the supplied private key.

Using Secrets from the Command Line

In this post we used the web console to create our application, including registering the private key for accessing our private Git repository hosted on GitHub. In the next post in this series, we will look at how to perform the same steps of creating the secret in OpenShift, but using the command line. We will also look at how you can add an annotation to a secret so that OpenShift automatically knows which source code repositories it should be used with.

Access the rest of the series here:

OpenShift Container Platform, OpenShift Dedicated, OpenShift Ecosystem, OpenShift Online, OpenShift Origin