In this post, I will run through how to properly set your Windows machine up for use with GitHub. We will install the necessary software, configure SSH for authentication, and GPG to sign off our commits.
Skip to the TL;DR section if you already know what you're doing!
Git
Install git if you haven't already done so.
> winget install Microsoft.Git ;
Found Microsoft Git [Microsoft.Git] Version 2.40.1.0.0
This application is licensed to you by its owner.
Microsoft is not responsible for, nor does it grant any licenses to, third-party packages.
Downloading https://github.com/microsoft/git/releases/download/v2.40.1.vfs.0.0/Git-2.40.1.vfs.0.0-64-bit.exe
██████████████████████████████ 55.2 MB / 55.2 MB
Successfully verified installer hash
Starting package install...
Successfully installed
Verify that the installation is working.
> git --version ;
git version 2.40.1.vfs.0.0
SSH
ssh-agent
Verify that the ssh-agent is running. It should have been included with your installation of Git (install Git)
> Get-Service ssh-agent
Status Name DisplayName
------ ---- -----------
Running ssh-agent OpenSSH Authentication Agent
In the case that ssh-agent is Stopped or Disabled, follow the advice on this stackoverflow answer to run the following on PowerShell on admin mode.
Get-Service -Name ssh-agent | Set-Service -StartupType Manual
SSH Config
Create an SSH key pair.
Remember to replace your_email@example.com with your own email address!
> ssh-keygen -t ed25519 -C your_email@example.com
Generating public/private ed25519 key pair.
Enter file in which to save the key (C:\Users\user_name/.ssh/id_ed25519):
Created directory 'C:\Users\user_name/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\Users\user_name/.ssh/id_ed25519.
Your public key has been saved in C:\Users\user_name/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:JDCPuYyjvbBApibR62OhJcBag/PGLbeunxYYD0BFc+w your_email@example.com
The key's randomart image is:
+--[ED25519 256]--+
|..o++. |
|. oB |
|.o + o . |
|+o=o E o |
|+B+Bo S |
|*+Oo= |
|**o+ o |
|=+o.o. |
|..+*+ |
+----[SHA256]-----+
Add to ssh-agent. You will need to do this whenever you first start up your computer.
> ssh-add 'C:\Users\user_name\.ssh\id_ed25519'
Identity added: C:\Users\user_name\.ssh\id_ed25519 (your_email@example.com)
Show your public key
> cat C:\Users\user_name/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGy2VTtWVdYHlxCfnh8Me3V++wZBBxcnN0QiwkWrFbMX your_email@example.com
Keep the terminal window open, you will need in the next steps.
GitHub Settings
Get to your personal GitHub Key settings by either:
- Click this link: https://github.com/settings/ssh/new
- Navigate to github > profile picture (top right) > Settings > SSH and GPG keys > New SSH Key
Fill in the form with the necessary information before submitting the form. You should see the new entry on the keys page:
GPG
Installing
Install GPG if you don't already have it
winget install GnuPG.GnuPG ;
Verify that the GPG is running and that you're running version > 2.
> gpg --version
gpg (GnuPG) 2.4.1
libgcrypt 1.10.2
Copyright (C) 2023 g10 Code GmbH
License GNU GPL-3.0-or-later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Home: C:\Users\user_name\AppData\Roaming\gnupg
Supported algorithms:
Pubkey: RSA, ELG, DSA, ECDH, ECDSA, EDDSA
Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
CAMELLIA128, CAMELLIA192, CAMELLIA256
Hash: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression: Uncompressed, ZIP, ZLIB, BZIP2
GPG Config
Generate a new key by entering gpg --full-generate-key.
I recommend using the default settings by hitting enter at each step and picking a secure password.
> gpg --full-generate-key
gpg (GnuPG) 2.4.1; Copyright (C) 2023 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
(1) RSA and RSA
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
(9) ECC (sign and encrypt) *default*
(10) ECC (sign only)
(14) Existing key from card
Your selection?
Please select which elliptic curve you want:
(1) Curve 25519 *default*
(4) NIST P-384
(6) Brainpool P-256
Your selection?
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0)
Key does not expire at all
Is this correct? (y/N) y
GnuPG needs to construct a user ID to identify your key.
Real name: Joel Lau
Email address: your_email@example.com
Comment: joel's desktop pc
You selected this USER-ID:
"Joel Lau (joel's desktop pc) <your_email@example.com>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: C:\\Users\\user_name\\AppData\\Roaming\\gnupg\\trustdb.gpg: trustdb created
gpg: directory 'C:\\Users\\user_name\\AppData\\Roaming\\gnupg\\openpgp-revocs.d' created
gpg: revocation certificate stored as 'C:\\Users\\user_name\\AppData\\Roaming\\gnupg\\openpgp-revocs.d\\DD2DB924314496969FFF1FC4FF7A0A2FE0F81BE3.rev'
public and secret key created and signed.
pub ed25519 2023-05-01 [SC]
DD2DB924314496969FFF1FC4FF7A0A2FE0F81BE3
uid Joel Lau (joel's desktop pc) <your_email@example.com>
sub cv25519 2023-05-01 [E]
Show the list of keys
> gpg --list-secret-keys --keyid-format=long
[keyboxd]
---------
sec ed25519/FF7A0A2FE0F81BE3 2023-05-01 [SC]
DD2DB924314496969FFF1FC4FF7A0A2FE0F81BE3
uid [ultimate] Joel Lau (joel's desktop pc) <your_email@example.com>
ssb cv25519/81D580E5588F5C57 2023-05-01 [E]
Print the key id you'd like to use
the key ID comes after the protocol name (FF7A0A2FE0F81BE3)
> gpg --armor --export KEY_ID_HERE
# e.g. gpg --armor --export FF7A0A2FE0F81BE3
Keep the terminal window open, you will need in the next steps.
GitHub Settings
Get to your personal GitHub Key settings by either:
- Click this link: https://github.com/settings/gpg/new
- Navigate to github > profile picture (top right) > Settings > SSH and GPG keys > New GPG Key
Fill in the form with the necessary information before submitting the form. You should see the new entry on the keys page:
Git (Again)
git config --global user.name "Joel Lau" ; # set user name
git config --global user.email your_email@example.com ; # set email address
git config --global core.editor "code --wait" ; # set VSCode as default text editor
git config --global --unset gpg.format ; # unset any previous GPG configuration
git config --global commit.gpgsign true ; # sign all commits using GPG
git config --global gpg.program 'C:\Program Files (x86)\gnupg\bin\gpg.exe' # tell git where to find gpg
git config --global user.signingkey KEY_ID_HERE ; # set the signing key (replace `KEY_ID_HERE`)
the resulting gitconfig file should look at follows:
[user]
email = joel.lau@protonmail.com
name = Joel Lau
signingkey = 977D5B2A1AA15946
[init]
defaultBranch = main
[core]
editor = code --wait
[gpg]
program = C:\\Program Files (x86)\\gnupg\\bin\\gpg.exe
[commit]
gpgsign = true
TL;DR
# NOTE: remember to use PowerShell on admin
# git
winget install Microsoft.Git ;
# start ssh-agent
Get-Service -Name ssh-agent | Set-Service -StartupType Manual ;
# create ssh keys - add to https://github.com/settings/keys
ssh-keygen -t ed25519 -C "your_email@example.com"
# add keys to ssh-agent
ssh-add ~/.ssh/id_ed25519
# gpg
# NOTE: remember to add 'C:\Program Files (x86)\gnupg\bin' to path
winget install GnuPG.GnuPG ;
# create gpg keys - add to https://github.com/settings/keys
gpg --full-generate-key ;
# show list of keys
gpg --list-secret-keys --keyid-format=long ;
# show key (the text after `sec 4096R/`)
gpg --armor --export KEY_ID_HERE
# set user name
git config --global user.name "Joel Lau" ;
# set email address
git config --global user.email your_email@example.com ;
# set VSCode as default text editor
git config --global core.editor "code --wait" ;
# unset any previous GPG configuration
git config --global --unset gpg.format ;
# sign all commits using GPG
git config --global commit.gpgsign true ;
# tell git where to find gpg
git config --global gpg.program 'C:\Program Files (x86)\gnupg\bin\gpg.exe'
# set the signing key (replace `KEY_ID_HERE`)
git config --global user.signingkey KEY_ID_HERE ;
Top comments (0)