Signing a commit using a GPG key is a way to securely authenticate the commit's origin by attaching a digital signature to it. This signature confirms that the commit was made by a specific person who possesses the corresponding private GPG key and can be trusted. The process involves using cryptographic techniques to generate a unique signature based on the commit data and the private key of the signer.
How Git commit signing works
When you sign a commit, Git uses your private GPG key to create a digital signature. This signature is unique to the specific commit content; any change in the commit would result in a different signature. The signature is then attached to the commit itself. Since the private key is secret and should only be accessible by its owner, the presence of a valid signature is strong evidence that the commit was indeed created by the owner of the corresponding public key.
Generating a GPG key
Step 1: Install GPG
First, ensure that GPG is installed on your system. You can install it through your operating system's package manager:
- For Ubuntu/Debian:
sudo apt-get install gnupg - For Fedora:
sudo dnf install gnupg - For macOS (using Homebrew):
brew install gnupg
Step 2: Generate a new GPG key
To generate a new GPG key, use the following command:
gpg --full-generate-key
During the key generation process, you will be prompted to select the type of key, key size, and expiration date. You will also need to provide user identification information such as your name and email address, which should match your Git configuration.
Managing GPG keys
Listing GPG keys
To list all GPG keys stored on your system:
gpg --list-keys
Exporting a GPG public key
After creating your GPG key, you need to export your public key to share it with others or add it to services like GitHub:
gpg --export --armor <email> > publickey.asc
Replace <email> with the email address used during the key generation.
Importing a GPG key
To import a GPG key from another user:
gpg --import publickey.asc
Deleting a GPG key
To delete a GPG key from your keyring:
gpg --delete-key <email>
Configuring Git to use your GPG key
Step 1: Configure Git with your GPG key
Find your GPG key ID:
gpg --list-keys
Configure Git to use this key by default:
git config --global user.signingkey <key-id>
Replace <key-id> with the ID of your GPG key.
Step 2: Sign commits using GPG
To sign a commit, add the -S flag to the git commit command:
git commit -S -m "Your commit message"
Verifying commit signatures
To verify the signatures of commits, use:
git log --show-signature
This command provides details on who signed each commit and whether the signature can be verified.
Handling common GPG errors
GPG: decryption failed: no secret key: This error occurs when you try to decrypt a message or verify a signature but don't have the appropriate private key. Ensure you have the private key that matches the public key used for signing.
Key is stored in legacy trusted.gpg keyring: Modern GPG versions recommend using
gpginstead of the oldergpg2and storing keys in a new keyring format. You might need to migrate your keys to the new format.
For further reading on signing Git commits with a GPG key, see the official Git documentation.
