Skip to content

signing.md

Latest commit

 

History

History
191 lines (125 loc) · 5.2 KB

signing.md

File metadata and controls

191 lines (125 loc) · 5.2 KB

Commit Signing Guidelines (DCO + GPG)

Both DCO sign-off and GPG signature signed commits are required for all pull requests to be merged successfully.

This guide makes it as easy as possible for you to set up your GPG key and DCO and GPG sign your commits.

Table of Contents

Definitions

Signature Flag Purpose GitHub Check
DCO Sign-off -s Confirms legal right to contribute code (required by CI bot). DCO Check
GPG Signature -S Proves you are the author of the commit (required by CI bot, requires GPG setup). Verified Badge

CRITICAL WARNING: To pass the DCO check and achieve the "Verified" status, all commits must be signed using both the -S and -s flags together.

Step-by-Step Setup

1. Generate a GPG Key

If you don't already have a GPG key:

gpg --full-generate-key

Choose:

  • Kind: ECC (sign and encrypt) default
  • Elliptic curve: Curve 25519 default
  • Expiration: 0 default (does not expire)
  • Name, Email: Must match your GitHub email
  • Passphrase: Set a strong passphrase that you'll need to remember

Learn more GPG key set-up documentation on GitHub

Once created, list your keys:

gpg --list-secret-keys --keyid-format LONG

Copy the key ID (looks like 34AA6DBC).

2. Add Your GPG Key to GitHub

Export your GPG public key:

gpg --armor --export YOUR_KEY_ID

Paste the output into GitHub:

3. Configure Git to Use Your GPG Key

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

4. Make Signed Commits

All commits must be signed using both DCO and GPG. Each time you create a commit, use -S and -s flags like this:

git commit -S -s -m "chore: your commit message"
  • -S = GPG sign
  • -s = DCO sign-off

⚠️ Ensure every commit in your branch follows this rule.

5. Verify Signed Status of Commits

To check that your commits are signed correctly:

git log --show-signature
  • Ensure each commit shows both GPG verified and DCO signed-off.

For a quick check of recent n commits: Note how many commits you have added, and replace 5 with that.

git log -n 5 --pretty=format:'%h %an %G? %s'

Legend:

  • G = Good (valid signature - you want to see G)
  • B = Bad (invalid signature)
  • U = Unknown (not signed)
  • E = Signed (but not verifiable locally)

Final Checklist

  • All commits signed with -S.
  • DCO added with -s
  • GPG key added to GitHub

Fixing Unsigned Commits

If you accidentally forgot to sign commits, there are two ways to fix them:

1. Soft Reverting Commits (Recommended for New Contributors)

Soft revert the impacted commits while keeping changes locally:

git reset --soft HEAD~n
  • HEAD~n = number of commits to go back
  • Example: To fix the last 3 commits: git reset --soft HEAD~3

Then, recommit each commit with proper signing:

git commit -S -s -m "chore: your commit message"

2. Retroactively Signing Commits

Alternatively, you can amend commits retroactively:

git commit --amend -S -s
git rebase -i HEAD~n            # For multiple commits
git push --force-with-lease

This is difficult and you may run into problems, for example, if you have merged from main.

Rebasing and Signing

Rebase operations will be required when your branch is behind the upstream main. We do not recommend merging from main, rebasing is strongly suggested. See Rebasing Guide for instructions on how to keep your main branch up to date and how to rebase.

When rebasing, you must use this command to ensure your commits remain DCO and GPG signed:

git rebase main -S

Note: git push --force-with-lease safely updates the remote branch without overwriting others' changes.

Still Need Help?