Alpine Linux on WSL
Sign your commits on Github
Or, Configuring Keychain for SSH and GPG keys
I have been self-abducted for the last 3 months in a dark closet writing code for the U.S. Gov’t, that closet being my home in Brooklyn. As you can imagine, I was so engrossed in my work that my writing in Medium took a heavy hit.
I’m happy to be back in form today with a new story about adding GPG signatures to Git commits. As most things in this publication for the last 2–3 years, this story is relevant if you (like me) are one of the niche users of Alpine Linux in Windows Subsystem for Linux (WSL).
Either way, I hope after a few tumultuous years of pandemic and lock downs everyone’s staying mentally and physically safe out there. Seriously, please take care of yourselves and those around you!!
Without further ado…
Install system dependencies
The GPG package is not available in Alpine
v3.14 or below. It is currently only available in Alpine
v3.15 and above.
To add GPG in Alpine, type
sudo apk add gpg:
Similar to an SSH key, which can also be used to authenticate to Github, GPG keys are easier to use if managed using an agent and a keychain. The purpose of the agent is to load SSH or GPG keys. The purpose of the keychain is to manage the agent, and to ensure only one agent is running at once.
For GPG keys in Alpine Linux, the
gpg-agent package takes care of loading the keys from disk into memory. The
keychain package takes care of managing agents for both SSH and GPG keys.
sudo apk add keychain gpg-agent will take care of installing these two packages.
Configure keychain in Bash
Since the keychain package manages the agents, you only need to invoke the keychain binary, no need to invoke either GPG or SSH agents. All you need in your
.bashrc or equivalent is the following template:
--dir ~/.ssh/.keychain \
--gpg2 --agents gpg,ssh \
<path to your ssh key> \
<path to your gpg key>source ~/.ssh/.keychain/$HOST-sh
source ~/.ssh/.keychain/$HOST-sh-gpg# Set GPG environment.
Opening a new window will execute your
.bashrc, which will then execute the keychain binary with the above parameters. When both SSH and GPG agents are being invoked by the keychain, the output should look something similar to this:
In this example keychain does not give any output about adding GPG keys because I haven’t added any yet, creating a GPG key and adding it to the agent is the next step.
Creating a new GPG key
To create a new GPG key use the command
gpg --full-generate-key --expert:
Select option #9,
ECC and ECC, then select option #1,
If you run into an error that says
gpg: failed to start agent , it means that you haven’t installed the GPG agent package correctly, and should visit the previous section of this story.
After selecting your elliptic curve algorithm above, GPG is going to ask for a few more details such as your name and email. Once you’ve filled those the key is generated and the output should be similar to the one below:
Congratulations, you have created your new GPG key!
But wait, there’s more!
When you create a new GPG key for the first time, a master key is created. That master key should be used to create additional keys (called sub keys) for different roles.
To add a sub key for signing commits sent to Github, Bitbucket, etc., you can use the command:
gpg --expert --edit-key <your master key id>
Once you enter that command, you are presented with a
Once you type
addkey in the prompt, GPG is going to ask you what kind of sub key you want to create. In this case I’m only interested in creating a key for signing Git commits, so I will select option #10:
ECC (sign only).
Then select option #1,
Curve 25519 :
Once the new sub key is created, you will notice that the master key will gain a new entry with the specified usage
S which, stands for signing:
Make sure to type
save in the
gpg> prompt or otherwise your changes will be thrown out!
Export GPG key to Github
After the sub key is created, use this command to print the sub key in a format that you can paste into Github:
# gpg --armor --export <your signing sub key id here>
gpg --armor --export AAB64F7FBD193141
Then go to github.com/settings/profile and click where it says SSH and GPG keys:
From the SSH and GPG keys page select
New GPG key:
You will get a text box where you can paste the output from the GPG export command above:
Configure Git to use GPG key
Once you save your signing key into your Git provider, you will want to configure your local Git to use your GPG key for signing commits.
This is something that you can do globally (use the same key for all projects), or on a per-repository basis. I for example might use one signing key for verifying my employer’s commits, and another signing key for all my open source contributions into Drupal or NPM.
The following commands will configure my local Git to use signing key
AAB64F7FBD193141 for all my local Git projects, since the majority of my projects are employer related:
git config --global user.email "firstname.lastname@example.org"
git config --global user.name "Richard Allen"
git config --global user.signingkey AAB64F7FBD193141
Important: you need to make sure that the name and email you specified when previously creating the GPG key matches the
user.name parameters you will enter into
git config, otherwise Git might not be able to sign your commits.
Push your changes to your repo !
With GPG up and running, next time you push to your remote Github repo, you will see that your commits are being signed:
If you click on the Verified button next to each commit, a pop up will show you the details about who signed that particular commit, and which GPG key was used for the signature:
GPG agent giving you grief? I’ve replicated these steps with decent success:
# kill and restart the gpg agent
gpgconf --kill gpg-agent# restart Alpine on WSL
wsl.exe -t Alpine
If the agent doesn’t want to talk to you:
Error connecting to agent: Connection refused
Check again your
.bashrc or equivalent configuration file. Depending on the Windows version, you may have to change the following lines:
In Windows 10, the correct environment variable is
$HOST , whereas in Windows 11,
$HOSTNAME is valid and
$HOST does not exist.
I forgot what keys do I have:
I want to list the public keys currently available:
gpg -k --keyid-format LONG
Same, but using fingerprints:
gpg -k --keyid-format LONG --fingerprint
Signing commits or tags is not something necessarily for everyone to partake on, and every developer or organization should weight the advantages and disadvantages prior to integrating it to their development workflow. There has definitely been healthy amount of discussion for the last 20 years regarding the subject, but here’s a list I compiled to get you started if you fancy to dig deeper into the subject:
- Emily Williams Cryptography 101: Symmetric Encryption story, based on Stanford University’s Cryptography I course on Coursera.
- A case against using GPG and signing commits by Dan Lorenc from Chainguard (a Kubernetes and Docker security provider): Should You Sign Git Commits?
- Fellow Medium writer Risan Bagja’s article on switching to ECC algorithm Ed25519.
- Current GNU Privacy Guard 2 (GPG) release on Alpine (Edge), version 2.2.x.
- GNU Privacy Guard homepage.
- ECC (Elliptic Curve Cryptography) is supported starting in GPG version 2.1. Release notes for GPG 2.1.
- GPG 2.1 release notes regarding ECC support.
- RFC 6637 Elliptic Curve Cryptography (ECC) in OpenPGP, June 2012.
- Stack Overflow, ECC in (Open)PGP, asked in 2013. Another S.O. question, asked in 2013: How can I use GnuPG with ECDSA keys?
- Some of the configuration files I use my Alpine WSL instances.
- Github: Adding a new GPG key to your GitHub account.
- Git Handbook: 7.4 Git Tools — Signing Your Work
- Another article: How (and why) to sign Git commits.
- On a deeper and more philosophical end: What are the advantages and disadvantages of cryptographically signing commits and tags in Git?
- A Git Horror Story: Repository Integrity With Signed Commits