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
Sign an individual commit:#
git commit -S -m "commit message here"
GitHub has additional documentation on signing commits.
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