Setting up SSH keys for Azure DevOps

Problem

You'd like to clone Azure Devops git repositories, push and pull git commits without using tokens and/or passwords.

Solution

1. Setup/Ensure SSH directories

In your home directory, ensure that you have a directory named .ssh, otherwise make it and give it the appropriate permissions (user read-write & execute):

mkdir -m 0700 -p ~/.ssh

2. Check for existing SSH keys

Before you generate a new SSH key, you should check your local machine for existing keys.

ls -al ~/.ssh

Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for Azure Devops (and GitHub) are one of the following.

id_rsa.pub

If you don't have a supported public and private key pair, or don't wish to use any that are available, generate a new SSH key.

3. (If desired) generate a new SSH keypair

This command creates a new SSH key with the rsa algorithm, using the provided email as a label:

ssh-keygen -t rsa -b 4096 -C "your_email@wustl.edu"

When you're prompted to "Enter a file in which to save the key", you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ALGORITHM with your custom key name.

Generally you want to place this key inside your ~/.ssh directory, so you can enter a file name like: ~/.ssh/id_rsa_azure_devops.

You also will be prompted to type a password or passphrase associated with you SSH key; feel free to keep it empty or not depending on your security preferences.

There will be two new files inside your ~/.ssh directory now:

id_rsa_azure_devops - this is your private key; don't share this with anyone
id_rsa_azure_devops.pub - this is your public key; share this with the public

4. Add your key to the SSH agent configuration

First, check to see if your ~/.ssh/config file exists in the default location:

ls -al ~/.ssh/config

If it doesn't exist, please create it by running the following command:

touch ~/.ssh/config

Open the ~/.ssh/config file with your favorite editor and please add in the following lines

    # to setup azure devops ssh keys
    Host ssh.dev.azure.com
      User git
      Hostname ssh.dev.azure.com
      PreferredAuthentications publickey
      IdentityFile ~/.ssh/id_rsa_azure_devops
      AddKeysToAgent yes
      UseKeychain yes

If you chose not to add a passphrase to your key, you should omit the UseKeychain line.

5. Add your SSH private key to the ssh-agent and store your passphrase in the keychain.

Start the ssh-agent in the background.

eval "$(ssh-agent -s)"

Run the ssh-add command to formally add the key to the ssh-agent:

ssh-add ~/.ssh/id_rsa_azure_devops

If you chose to use a passphrase with with your key, then try the following ssh-add command instead:

ssh-add --apple-use-keychain ~/.ssh/id_rsa_azure_devops

This will appropriately store your passphrase associated with the key into Apple's Keychain system.

6. Add your SSH key to your Azure DevOps account

a. copy the contents of your public SSH key with the following command:

On MacOS:

cat ~/.ssh/id_rsa_azure_devops | pbcopy

On Windows:

type %USERPROFILE%/.ssh/id_rsa_azure_devops | clip

b. Go to the main devops page, https://dev.azure.com/wustl-i2/ , and in the top right corner, click on the "User Settings" button and choose the "SSH public keys" option. See the image below:

Azure DevOps SSH Public Key Settings

c. Press the "New Key" button on the top right corner
d. In the resulting "New SSH Key" dialog:
i. place an appropriate name for your Key (e.g. "username-devops") in the "Name" field.
ii. paste in the contents of your clipboard in the "Public Key Data" field.
iii. Press the "Add" button on the bottom right corner.

Discussion

SSH is an amazing, wonderful tool and there is a lot to it--enough to fill a book! Having SSH key setup with DevOps (and GitHub too!) makes the development and automation of processes involving git repositories much more easier to manage and handle!

Common Troubleshooting Issues

Please fill me in!

Data Sources

Platforms

Teams