# 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
  ```powershell
  git --version
  ```

- **Azure DevOps account** with access to your organization/project
  - If you don't have one, create a free account at [dev.azure.com](https://dev.azure.com)

- **PowerShell 7+ or Bash terminal** for running commands
  ```powershell
  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:

```powershell
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. See the note at the end of this guide for more information.

### Save Location

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

```
Enter file in which to save the key (/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:

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

### Verify Key Generation

Check that your keys were created:

**Linux/Mac:**
**Windows PowerShell:**
```powershell
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:

**Linux/Mac:**
```bash
cat ~/.ssh/id_rsa.pub
```

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

**Windows Command Prompt:**
```cmd
type %USERPROFILE%\.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 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:

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

**Example** (replace placeholders with your actual values):
```bash
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
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/azure-devops-clone-ssh.png)
*Select SSH from the clone dialog to get your repository's SSH URL*

### Convert Existing HTTPS Repository to SSH

If you already cloned a repository using HTTPS, you can switch it to SSH:

```bash
cd /path/to/your/repository
git remote set-url origin git@ssh.dev.azure.com:v3/{organization}/{project}/{repository}
```

**Verify the change:**
```bash
git remote -v
```

You should see SSH URLs:
```
origin  git@ssh.dev.azure.com:v3/myorg/git-workshop/great-print-project (fetch)
origin  git@ssh.dev.azure.com:v3/myorg/git-workshop/great-print-project (push)
```

### Daily Git Operations

All standard Git commands now work seamlessly with SSH:

```bash
# 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)
- **SSH Key Best Practices**: [https://security.stackexchange.com/questions/tagged/ssh-keys](https://security.stackexchange.com/questions/tagged/ssh-keys)
- **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

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

# Display public key (Linux/Mac)
cat ~/.ssh/id_rsa.pub

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

# Test SSH connection
ssh -T git@ssh.dev.azure.com

# Clone with SSH
git clone git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

# Convert HTTPS to SSH
git remote set-url origin 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/mycompany/git-workshop/great-print-project
```

---

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