To add a signature in GitHub, you must first generate a cryptographic key pair (either GPG or SSH) on your local machine, register the public key with your GitHub account, and configure Git to use that key when signing your commits.
This process provides a "Verified" badge on your commits, establishing authenticity and integrity.
Why you should sign your commits
By default, Git allows any user to set their name and email, which means a commit's author can be easily spoofed. Signing your commits with a private key ensures that the changes are verifiably from you and that the content has not been tampered with since it was signed.
The key benefits of signed commits include:
- Authenticity: Confirms that the commit was created by the person who holds the private key.
- Integrity: Guarantees that the commit's content has not been altered.
- Trust: Provides assurance to collaborators that the code is from a verified source.
- Accountability: Creates a verifiable audit trail for code changes.
Method 1: Using GPG to sign your commits
GPG (GNU Privacy Guard) is a popular and robust method for signing commits. This process involves generating a GPG key, adding it to your GitHub account, and configuring Git.
Step 1: Install GPG
First, ensure GPG is installed on your system.
- macOS:
brew install gpg - Windows: Install
Git for Windows, which includes GPG tools in Git Bash. - Linux (Debian/Ubuntu):
sudo apt install gnupg
Step 2: Generate a GPG key pair
- Open your terminal or Git Bash and run:
$ gpg --full-generate-key - Follow the prompts. For most users, these are the recommended options:
- Key Kind: Select
(1) RSA and RSA. - Keysize:
4096bits for stronger encryption. - Expiration:
0(key does not expire) is a common choice, but you can set a custom expiration date.
- Key Kind: Select
- Enter your personal information, ensuring your email address matches the email associated with your GitHub account. If you use GitHub's no-reply email, use that instead.
- Enter and confirm a secure passphrase when prompted.
Step 3: Configure Git with your GPG key
To set your GPG signing key in Git, first list your secret keys to find your key ID using $ gpg --list-secret-keys --keyid-format=long. Then, configure Git globally with $ git config --global user.signingkey YOUR_KEY_ID, replacing YOUR_KEY_ID with the ID you copied.
Step 4: Add your GPG key to GitHub
Export your public GPG key using $ gpg --armor --export YOUR_KEY_ID. In your GitHub settings, navigate to SSH and GPG keys, click New GPG key, provide a title, paste the key, and confirm with your password.
Step 5: Sign your commits
To sign individual commits, use the -S flag with git commit. To sign all commits in a repository by default, run $ git config commit.gpgsign true. For global signing by default, use $ git config --global commit.gpgsign true.
Method 2: Using SSH to sign your commits
Using an SSH key is a simpler option, especially if you already use one for authentication. This method requires Git version 2.34 or later.
Step 1: Configure Git for SSH signing
Configure Git to use the ssh format for GPG with $ git config --global gpg.format ssh. Then, specify the path to your SSH public key using $ git config --global user.signingkey ~/.ssh/id_ed25519.pub, adjusting the filename if needed.
Step 2: Add your SSH key to GitHub
Copy the contents of your SSH public key file. In GitHub settings under SSH and GPG keys, click New SSH key. Select Signing Key as the key type, add a title, paste your public key, and click Add SSH key.
Step 3: Sign your commits
Sign commits using the -S flag with git commit. You can also configure Git to sign commits by default per repository or globally using $ git config commit.gpgsign true and $ git config --global commit.gpgsign true respectively.
What if a commit shows "Unverified"?
If a commit shows "Unverified" after setup, common reasons include:
- The email address in the key does not match a verified email on your GitHub account.
- The key was added to GitHub after the commit was pushed. You may be able to add an expired or revoked key for verification of older commits.
- The key is incorrect or has expired.
- Using GitHub's "Rebase and merge" option, which creates a new, unsigned commit. Rebase and merge locally before pushing to maintain signed history.