First Time SSH Configuration on a Workflow

Scope

This document outlines SSH configuration on a Metworx workflow, with a specific focus on allowing interactions with a user's GitHub account.

SSH Configuration Overview

One of the ways to allow interactions with GitHub on a Metworx Workflow is via SSH protocol and SSH key pair authentication.

A user's home directory is under /data on each Metworx disk, and once set up, the user's configuration is preserved on the user's disk. So, SSH key authentication with a GitHub Enterprise (aka GHE) instance or GitHub.com only needs to be configured once per Metworx disk, persisting each time that existing disk is used on a Metworx workflow moving forward.

Configuring Github to Connect via SSH on Metworx

Below are high-level steps to configure your GitHub account to connect via SSH on your Metworx workflow. Each of these steps are described in more detail in each corresponding subsection.

  • Generate SSH key pairs on your Windows or Mac workstation

  • Copy in the private SSH key to your Metworx Workflow (disks)

    • This can be done on multiple workflows, allowing you to not have to configure multiple public SSH keys on Github
  • Configure your Github account with your public SSH key

Generating SSH Key Pairs

Creating public/private key pairs on Windows, Linux (same steps on Mac) are described here Steps to create SSH KeyPairs.

NOTE: On a Metworx Workflow, id_rsa and id_rsa.pub keys are automatically created and placed in the ~/.ssh/ directory on the Metworx disk and can be used.

Copying the SSH Private Key to your Metworx Workflow

If a new SSH key pair is created, the private key should be added to your Metworx Workflow.

By convention, it is recommend you use a ~/.ssh/ directory as a place to store your SSH keys on your Metworx workflow. To do so, follow these steps:

  1. If you are using a 20.12 or earlier Metworx series, log into RStudio Server Pro. If you are using a more recent Metworx series (21.08 onward) log into RStudio Workbench and start an RStudio Session. rstudio interfaces Using RStudio's "Upload" functionality, upload your private SSH key to your working directory. In this example, the file is id_rsa. On Linux/Mac, the private key is id_rsa on Linux/Mac, but on Windows it is username.pem.  
  2. Using the RStudio Terminal, move the uploaded file to ~/.ssh with the following:
mkdir -p ~/.ssh
mv id_rsa ~/.ssh/id_rsa_git
chmod 400 ~/.ssh/id_rsa_git

Configure GitHub Account with your Public SSH Key

If a new SSH key pair is created, the public key should be added to your GitHub account, as detailed here.

Configure SSH/Git to Offer Specific Private key for Authentication with GitHub/GHE

If an SSH key file name other than ~/.ssh/id_rsa is used, edit the ~/.ssh/config file to tell SSH and Git to use the specific private key for a given GitHub or GitHub Enterprise (GHE) instance.

The contents of the ~/.ssh/config file will be as follows:

Host INSERT_YOUR_GHE_INSTANCE_INFO_HERE
  IdentityFile /path/to/private_key
  User git

For example, if the GHE instance for the repos is ghe.metrumrg.com and the key, like prescribed in the example above, is ~/.ssh/id_rsa_git, the .ssh/config file would be as follows:

Host ghe.metrumrg.com 
  IdentityFile ~/.ssh/id_rsa_git
  User git

(Optional) Using Personal Access Token (PAT) Instead of SSH

In some cases, it may be more convenient to use PAT than SSH keys. Moreover, on rare occasions when SSH access to GitHub/GHE is blocked, but HTTPS is not, PAT can be used instead of SSH keys to authenticate with GitHub. For detailed instructions, please refer to Git documentation