LISTING KEYS

gpg --list-secret-keys --keyid-format=long
gpg --list-keys --keyid-format=long

EXPORTING (BACKUP)

Run all of these whenever you generate a new key, or periodically as a backup refresh.

cd ~/temp

# Public key (safe to share, upload to github/forgejo, post anywhere)
gpg --armor --export [email protected] > public-key.asc

# Secret key (SENSITIVE — treat like a password)
gpg --armor --export-secret-keys [email protected] > private-key-backup.asc

# Secret subkeys only (if you ever split a signing subkey off the master key)
gpg --armor --export-secret-subkeys [email protected] > private-subkeys-backup.asc

# Revocation certificate (lets you revoke the key if it's ever compromised or lost)
Copy-Item ~/.gnupg/openpgp-revocs.d/*.rev revocation-cert-backup.asc

# Owner trust settings (optional, only matters if you've set trust on OTHER people's keys)
gpg --export-ownertrust > ownertrust-backup.txt

Store private-key-backup.asc and revocation-cert-backup.asc somewhere secure and offline — password manager, encrypted USB, encrypted cloud vault. Anyone who has the private key file (and your passphrase, if you set one) can sign as you. Never commit these to a git repo, even a private one.

public-key.asc and ownertrust-backup.txt are not sensitive.


IMPORTING (RESTORE)

On a new machine, or after a wipe/reinstall:

cd ~/temp

gpg --import public-key.asc
gpg --import private-key-backup.asc
gpg --import-ownertrust ownertrust-backup.txt   # optional

Then re-set ultimate trust on your own key (import doesn’t always carry this over):

gpg --edit-key [email protected]
# at the gpg> prompt:
trust
5
y
quit

Verify it worked:

gpg --list-secret-keys --keyid-format=long

Point git at it again (same as original setup):

git config --global gpg.format openpgp
# key ID last 16 hex chars of fingerprint (579E49DA6CD712F6A1DF91CF5C0177D2FB3767BC), tells git which
# key to sign commits with. Public keys and their IDs go on GitHub/Forgejo openly, in commit metadata,
# everywhere — that's the point, lets others verify your signature.
git config --global user.signingkey 5C0177D2FB3767BC1
git config --global commit.gpgsign true

GENERATING A NEW KEY

gpg --quick-generate-key "Name <email>" ed25519 sign 2y
  • sign — signing-only key (what you want for git commit signing)
  • 2y — expiry; renew before it lapses with gpg --quick-set-expire <fingerprint> 2y
  • Immediately run the EXPORTING steps above for the new key, including the revocation cert.

ADDING THE PUBLIC KEY TO GITHUB / FORGEJO

Paste the contents of public-key.asc into:

  • GitHub: Settings → SSH and GPG keys → New GPG key
  • Forgejo: Settings → SSH / GPG Keys → Add Key

Same public key works on both — the signature is embedded in the commit object itself, so once it’s registered on a host, that host can verify any commit signed with the matching private key, regardless of where the commit was authored or mirrored from.


IF THE KEY IS LOST OR COMPROMISED

  1. Import the revocation cert to invalidate the key everywhere you have it imported:
    gpg --import revocation-cert-backup.asc
  2. Re-upload the now-revoked public key to github/forgejo so they mark past signatures accordingly and stop trusting new ones.
  3. Generate a new key and repeat setup.