Blog
Painless Git+SSH Setup

Painless Git+SSH Setup

May 25, 2024

In this guide, we’ll walk you through the steps to generate an SSH key pair, add it to your Git account, and configure your local Git setup for seamless integration.

By the end, you’ll have a more efficient and secure Git environment that enhances your productivity and protects your code.

Why?

Setting up Git to use SSH can significantly enhance your workflow by providing a secure and convenient method for authenticating your repositories. Whether you’re a seasoned developer or new to version control, configuring Git with SSH keys streamlines the process of pushing and pulling code, eliminating the need to repeatedly enter your username and password.

How?

ℹ️
Although I will use GitHub as my Git hosting provider in this guide, this setup works for any other Git hosting provider. Just replace “github” with “gitlab”, “bitbucket”, etc.

Create the .ssh Directory and SSH config 

mkdir -p ~/.ssh/keys/
touch ~/.ssh/config
New-Item -ItemType Directory -Path "$env:UserProfile\.ssh\keys"
New-Item -ItemType File -Path "$env:UserProfile\.ssh\config"

If everything went successfully, the .ssh directory tree will look like:

    • config
      • ℹ️
      Creating the .ssh/keys directory helps manage multiple SSH keys if needed.

      Generate an SSH Key Pair 

      ssh-keygen -t ed25519 -b 4096 -a 100 -C private-pc -f ~/.ssh/keys/githb
      ssh-keygen.exe -t ed25519 -b 4096 -a 100 -C private-pc -f "$env:UserProfile\.ssh\keys\github"
      ℹ️
      You can set a password (recommended) or skip it by pressing <Enter> twice.

      Now your .ssh tree will look like:

      • config
        • github
        • github.pub

      • Explanation

      • -t: Type of key, here ed25519.
      • -b: Number of bits, here 4096.
      • -a: Number of KDF rounds, here 100.
      • -C: Comment, defaults to <username>@<computer name>.
      • -f: File location and name, here “github”. This creates two files:
        • .ssh/keys/github: Private key.
        • .ssh/keys/github.pub: Public key.
      ℹ️
      Read more about available configuration options for ssh-keygen here.

      Create the SSH Config File

      .ssh/config
      1
2
3
4
5
6
7

      Host github.com
  Hostname github.com
  User git
  IdentityFile %d/.ssh/keys/github
  AddKeysToAgent yes
  RequestTTY no
  SessionType none
      ℹ️
      Read more about available configuration options for ssh_config here.

      Explanation

      The key to the configuration is the first line: Host github.com. This tells SSH to use the defined settings whenever you connect to github.com:

      ssh github.com

      SSH will use the settings provided:

      • Hostname: The address to connect to.
      • User: The user to authenticate as, usually “git”.
      • IdentityFile: Path to the private key, %d is the user home directory.
      • AddKeysToAgent: Adds the key to the ssh-agent, usful if the SSH key is password protected.
      • RequestTTY: Set to no as no shell is needed.
      • SessionType: Set to none since no commands are executed on the Git hosting provider.

      Add Your Key to the Git Hosting Provider

      The general flow is:

      Copy the SSH Public Key to Your Clipboard 

      cat ~/.ssh/keys/github.pub
# Then select and copy the displayed contents
      Alternative Way
      Alternatively, locate the hidden .ssh folder, open the file in a text editor, and copy it to your clipboard.

      Add the Public Key to Your User’s SSH Keys

      Follow the instructions for your provider:


      Bitbucket

      Codeberg

      Github

      Gitlab

      ⚠️
      If your provider is not listed, please refer to their official documentation.

      Verify SSH Access

      Run:

      ssh github.com

      If you don’t get any errors, the setup is successful. 🥳

      Configure Git to Use SSH Instead of HTTPS 

      git config --global url.ssh://git@bitbucket.org/.insteadOf https://bitbucket.org/
      git config --global url.ssh://git@codeberg.org/.insteadOf https://codeberg.org/
      git config --global url.ssh://git@github.com/.insteadOf https://github.com/
      git config --global url.ssh://git@gitlab.com/.insteadOf https://gitlab.com/
      ℹ️
      You can omit the --global flag while inside a git repository to configure that repository only.

      Tips & Tricks

      Set Private Key File Permissions

      If you encounter:

      Permissions for ‘private-key’ are too open.

      Run the following:

      chmod 400 ~/.ssh/keys/github
      New-Variable -Name Key -Value "$env:UserProfile\.ssh\keys\github"
Icacls $Key /c /t /Inheritance:d
Icacls $Key /c /t /Grant ${env:UserName}:F
Icacls $Key /c /t /Remove:g Administrator "Authenticated Users" BUILTIN\Administrators BUILTIN Everyone System Users
Remove-Variable -Name Key

      Migrating to a Different Git Hosting Provider

      To switch providers, change the Hostname and IdentityFile in the SSH config to the new provider and add a new Host block for it.

      All existing repositories will point to the new provider, and new repositories will work as expected.

      Migrate from Github to Codeberg Config Example
      .ssh/config
       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

      # Edit old "Host" block to automatically push code to new git hosting provider
Host github.com
  Hostname codeberg.org
  IdentityFile %d/.ssh/keys/codeberg
  # Rest of parameters

# New "Host" block to support new repositories
Host codeberg.org
  Hostname codeberg.org
  IdentityFile %d/.ssh/keys/codeberg
  # Rest of parameters
      Should I Attend a Shortcut College for a Technical Role?CI/CD for your CV