Setting up your Verily Workbench SSH key

Introduction

If you’d like to clone Git repositories to your Verily Workbench workspace, you can create a Workbench-managed SSH key, and tie it to your GitHub account. This key will be automatically added to the ssh-agent in your workspace cloud environments. Then, when you clone Git repos, either ‘by hand’ or via Git references as described in Add a Git repository to a Workbench workspace, authentication will work seamlessly. This means that you can perform any git operation with the Git extension in a notebook without any manual setup.

Set up your Workbench SSH key with GitHub

The Workbench-managed SSH key is not automatically tied to your GitHub account. After you’ve generated your SSH key, you will need to add the public key to your GitHub account. Once the public key is known by the GitHub account, you are good to go.

Note: There can only be one SSH key per Workbench user account. GitHub does not allow having one SSH key for multiple GitHub accounts, so we encourage you to work with one GitHub account per Workbench cloud environment. If you must switch between different GitHub accounts (e.g. one for personal and one for business) in your environment, you can upload your personal SSH key that is tied to your alternative GitHub account from your local computer and add it to the VM SSH agent by following this guide.

Step 1: Get the Workbench SSH key

You can get the Workbench SSH key through the Workbench CLI or the web UI.

Workbench CLI

terra user ssh-key get

If you received an error and you have never visited the web UI, you might not have a key. In that case, run

terra user ssh-key generate

Optionally, run terra user ssh-key generate --save-to-file to save the SSH key pairs to your local machine. For details on setup to use the SSH on your local machine (instead of your cloud environment), see the following section on “Working on a Local Machine”.

Web UI

1. Navigate to the user profile:

   

2. Copy the SSH public key:

Step 2: Add the Workbench SSH key to your GitHub account

Copy the public SSH key, and then follow the GitHub instructions. We recommend that you name the key something like “Workbench SSH key”, to distinguish it from your personal SSH key.

[Optional] Step 3: Configure SSO

If your GitHub organization sets up SAML Single Sign On (SSO), select Configure SSO on the Workbench ssh key that you added in Step 2 and select your organization to authorize your key for.

Now you are all set up!

Working on a Local Machine

This is only needed if you are not on a cloud environment and you don’t have an SSH key set up on your local machine.

terra user ssh-key generate --save-to-file
mv terra_id_rsa ~/.ssh
mv terra_id_rsa ~/.ssh.pub
eval "$(ssh-agent -s)"
open ~/.ssh/config

In the config file, add:

Host *
  AddKeysToAgent yes
  IgnoreUnknown UseKeychain
  UseKeychain yes
  IdentityFile ~/.ssh/terra_id_rsa

How to regenerate an SSH key

If you think the SSH key is compromised (e.g. the private key is leaked), you may regenerate a new SSH key. However, by regenerating the SSH key, any previous cloud environment that is linked with the old SSH key will not be automatically updated. It is the responsibility of the user to revoke the SSH key on their GitHub account.

You can regenerate an SSH key from both the Workbench CLI or the web UI.

Workbench CLI

terra user ssh-key generate

Web UI

1. Navigate to the user profile:

   

2. Click “Regenerate”:

   

How to revoke an old SSH key on the GitHub account

Log in to your GitHub account and go to https://github.com/settings/keys. From there you can revoke your previously linked Workbench SSH key. Then you can attach the new key if you wish.