Signing GitHub Commits¶
master branch now only accepts verified commits to be confident that the changes come from a trusted source. To be verified, a commit must be signed with a certificate recognized by GitHub.
These instructions cover creating a GPG key, copying it to GitHub, and setting up
git to sign commits.
Although it’s possible to use S/MIME to sign commits with an X.509 certificate (e.g. as found on a smartcard), the certificate must be signed by an authority already trusted by GitHub. The list of trusted CAs is the same as the one trusted by the Mozilla browser. Note: The certificates on NASA PIV badges are not signed by a CA currently trusted by GitHub.
Setting up your GPG Key with Git and GitHub¶
The process is documented in detail by GitHub. Here are the highlights:
Install GPG if necessary
Source and binary releases are available at gnupg.org
Also available through many OS package managers. Examples:
brew install gpg
RPM-based Linux distro:
sudo yum install gnupg2or
sudo dnf install gnupg2
DEB-based Linux distro:
sudo apt install gnupg
scoop bucket add nonportable, then
scoop install gpg-np(Obtain Scoop)
It’s important to note that the email address used for the key must be identical to your GitHub commit email address
git config --global user.emailto find this if you’re unsure
Additional information on setting your commit email address, including using a
At the end of this process, you’ll have your new GPG key copied to your clipboard
Complete the instructions to find your key’s ID and configure
Profile photo → Settings → SSH and GPG keys → New GPG key
Paste the key
Add GPG key
gpg --list-secret-keys --keyid-format=long
From that output, copy the long ID (16 hexadecimal digits) from the
secline of the key you just generated (or existing one you want to use), e.g.
sec ed25519/A0B1C2D3E4F56789 2021-09-07 [SC]
Set your signing key:
git config –global user.signingkey A0B1C2D3E4F56789
Sign all commits by default:¶
git config --global commit.gpgsign true
Sign only commits for the current local repository by default:¶
git config --local commit.gpgsign true
It can be inconvenient to have to enter your GPG key passphrase for every commit. Invoking
gpg automatically starts the
gpg-agent program, which caches the key for a configurable amount of time. The
$HOME/.gnupg/gpg-agent.conf file contains options for
gpg-agent. Here is the complete list of
Example config file with some useful options:
# Set the time a cache entry is valid to 600 seconds. Each time a # cache entry is accessed, the entry’s timer is reset. default-cache-ttl 600 # Set the maximum time a cache entry is valid to 7200 seconds. After # this a cache entry will be expired even if it has been accessed recently. max-cache-ttl 7200 # MacOS only: Connect gpg-agent to the keychain via the pinentry program # from GPGtools. Run "brew install pinentry-mac" to install. pinentry-program /usr/local/bin/pinentry-mac
Pull-requesting a branch with unverified commits¶
If you attempt to PR a branch containing unsigned/unverified commits, merging will be blocked.
To fix this problem, you’ll need to overwrite the unverified commits.
Start by recommitting from the local repository of your development branch:
git rebase -i <commit before first problematic commit>
Your text editor will open up. Change every
Save the file and exit the editor.
git commit --amend -S, followed by
git rebase --continue. Repeat until you get a message like
Successfully rebased and updated refs/heads/<branchname>.
git push --force-with-lease
Adapted from stackoverflow