# Azure DevOps SSH Setup - Best Practices Guide

This guide provides comprehensive instructions for setting up SSH authentication with Azure DevOps. SSH is the recommended authentication method for secure Git operations.

## Why SSH is Best Practice

SSH (Secure Shell) keys provide a secure way to authenticate with Azure DevOps without exposing passwords or tokens. Here's why SSH is the security best practice:

**Security Benefits:**
- **No Password Exposure**: Your credentials never travel over the network
- **Strong Encryption**: Uses RSA cryptographic algorithms
- **No Credential Prompts**: Seamless authentication after initial setup
- **Revocable**: Individual keys can be removed without changing passwords
- **Auditable**: Track which key was used for each operation

---

## Prerequisites

Before starting, ensure you have:

- **Git 2.23 or higher** installed
  ```pwsh
  git --version
  ```

- **Azure DevOps account** with access to your organization/project
  - If you don't ask your organisation for an invitation

- **PowerShell 7+ or Bash terminal** for running commands
  ```pwsh
  pwsh --version
  ```

---

## Step 1: Generate SSH Key Pair

SSH authentication uses a key pair: a private key (stays on your computer) and a public key (uploaded to Azure DevOps).

### Generate RSA Key

Open your terminal and run:

```pwsh
ssh-keygen -t rsa
```

**Note about RSA:** Azure DevOps currently only supports RSA SSH keys. While newer algorithms like Ed25519 offer better security and performance, they are not yet supported by Azure DevOps.

### Save Location

When prompted for the file location, press `Enter` to accept the default:

```
Enter file in which to save the key (C:\Users\YourName\.ssh\id_rsa):
```

**Default locations:**
- **Windows**: `C:\Users\YourName\.ssh\id_rsa` and  `C:\Users\YourName\.ssh\id_rsa.pub`

### Passphrase (Optional but Recommended)

You'll be prompted to enter a passphrase, just press `Enter` no password is needed (recommended but not needed):

```
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```

### Verify Key Generation

Check that your keys were created:

**Windows PowerShell:**
```pwsh
dir $HOME\.ssh\
```

You should see two files:
- `id_rsa` - Private key (NEVER share this)
- `id_rsa.pub` - Public key (safe to share for upload to Azure DevOps)

---

## Step 2: Add SSH Public Key to Azure DevOps

Now you'll upload your public key to Azure DevOps.

### Navigate to SSH Public Keys Settings

1. Sign in to Azure DevOps at [https://dev.azure.com](https://dev.azure.com)
2. Click your **profile icon** in the top-right corner
3. Select **User settings** from the dropdown menu
4. Click **SSH Public Keys**

![Azure DevOps - User Settings Menu](./images/02_ssh_option.png)
*Navigate to your user settings by clicking the profile icon in the top-right corner*

### Add New SSH Key

5. Click the **+ New Key** button

![Azure DevOps - Add SSH Public Key Dialog](./images/03_add_new_key.png)
*Click '+ New Key' to begin adding your SSH public key*

### Copy Your Public Key

Open your terminal and display your public key:

**Windows PowerShell:**
```pwsh
type $HOME\.ssh\id_rsa.pub
```

The output will look like this:
```
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC2YbXnrSK5TTflZSwUv9KUedvI4p3JJ4dHgwp/SeJGqMNWnOMDbzQQzYT7E39w9Q8ItrdWsK4vRLGY2B1rQ+BpS6nn4KhTanMXLTaUFDlg6I1Yn5S3cTTe8dMAoa14j3CZfoSoRRgK8E+ktNb0o0nBMuZJlLkgEtPIz28fwU1vcHoSK7jFp5KL0pjf37RYZeHkbpI7hdCG2qHtdrC35gzdirYPJOekErF5VFRrLZaIRSSsX0V4XzwY2k1hxM037o/h6qcTLWfi5ugbyrdscL8BmhdGNH4Giwqd1k3MwSyiswRuAuclYv27oKnFVBRT+n649px4g3Vqa8dh014wM2HDjMGENIkHx0hcV9BWdfBfTSCJengmosGW+wQfmaNUo4WpAbwZD73ALNsoLg5Yl1tB6ZZ5mHwLRY3LG2BbQZMZRCELUyvbh8ZsRksNN/2zcS44RIQdObV8/4hcLse30+NQ7GRaMnJeAMRz4Rpzbb02y3w0wNQFp/evj1nN4WTz6l8= your@email.com
```

**Copy the entire output** (from `ssh-rsa` to and including your email address).


### Paste and Name Your Key

![Azure DevOps - Add SSH Public Key Dialog](./images/04_copy_paste_key.png)

6. In the Azure DevOps dialog:
   - **Name**: Give your key a descriptive name (e.g., "Workshop Laptop 2026", "Home Desktop", "Work MacBook")
   - **Public Key Data**: Paste the entire public key you just copied
7. Click **Save**

**Naming tip**: Use names that help you identify which machine uses each key. This makes it easier to revoke keys later if needed.

---

## Step 3: Using SSH with Git

Now that SSH is configured, you can use it for all Git operations.

### Clone a Repository with SSH

To clone a repository using SSH:

```pwsh
git clone git@ssh.dev.azure.com:v3/{organization}/{project}/{repository}
```

**Example** (replace placeholders with your actual values):
```pwsh
git clone git@ssh.dev.azure.com:v3/myorg/git-workshop/great-print-project
```

**How to find your SSH URL:**
1. Navigate to your repository in Azure DevOps
  ![Azure DevOps - Repositories](./images/05_repos.png)
2. Click **Clone** in the top-right
3. Select **SSH** from the dropdown
4. Copy the SSH URL

![Azure DevOps - Get SSH Clone URL](./images/06_choose_ssh.png)
*Select SSH from the clone dialog to get your repository's SSH URL*

### Daily Git Operations

All standard Git commands now work seamlessly with SSH:

```pwsh
# Pull latest changes
git pull

# Push your commits
git push

# Fetch from remote
git fetch

# Push a new branch
git push -u origin feature-branch
```

**No more credential prompts!** SSH authentication happens automatically.

---

## Additional Resources
- **Azure DevOps SSH Documentation**: [https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate](https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate)
- **Git with SSH**: [https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key)

---

## Quick Reference

### Common Commands

```pwsh
# Generate RSA key
ssh-keygen -t

# Display public key
type $HOME\.ssh\id_rsa.pub

# Clone with SSH. You can find this url on Azure DevOps
git clone git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

# Check remote URL
git remote -v
```

### SSH URL Format

```
git@ssh.dev.azure.com:v3/{organization}/{project}/{repository}
```

**Example:**
```
git@ssh.dev.azure.com:v3/novenco/software/git-workshop
```

---

**You're all set!** SSH authentication with RSA keys is now configured for secure, passwordless Git operations with Azure DevOps.