GPG key management for developers: avoiding the lockout

You set up GPG once, for signing commits or for a password store, and then you forget about it — until the day your laptop dies, or your home directory is wiped, and you realize the secret key is gone. That is not an inconvenience; it is a lockout. GPG has no password reset. If the secret key is lost, every encrypted file, every stored password, and every signature you could no longer verify is gone with it.

Why there is no recovery

pass, for example, encrypts each entry to your public key. Decryption requires the matching secret key. No secret key, no entry — no support ticket will fix it, because the design has no back door. The same logic applies to anything else encrypted or signed with GPG: the secret key is the only thing that matters, and everything else is a copy of it.

The lockout has three variants: the key is lost (disk failure, deleted directory), the passphrase is forgotten, or the key is compromised. The practices below handle all three.

The practices that prevent lockout

Back up the secret key, offline. Export it once and store it somewhere not attached to the machine:

gpg --export-secret-keys --armor > secret-key-backup.asc

Print a copy for an envelope in a safe, or put it on a USB drive in a drawer. An offline backup survives disk failure and ransomware; an encrypted one in your cloud drive also survives theft of the laptop.

Generate a revocation certificate. If a key is compromised, you want to revoke it so others stop trusting it:

gpg --gen-revoke 0x1A2B3C4D

Store the output separately from the backup — ideally printed. If the key is ever lost or stolen, the certificate lets you publish a revocation without needing the secret key.

Set an expiry — and extend it. An expiry date is a safety valve, not a deadline. If a key expires, signatures stop verifying, but you can extend it at any time:

gpg --edit-key 0x1A2B3C4D

With a fixed expiry you know that a key you lost will stop being trusted eventually, instead of living forever.

Use subkeys for daily work. Keep the master key in the offline backup and generate encryption and signing subkeys for the machine you use daily. If the laptop is stolen, you revoke the subkeys and keep the master. The daily damage is limited to what the subkeys could do.

Protect the passphrase, recoverably. A strong passphrase is useless if it is only in your head. Store it in a password manager you can still reach, or write it down with the backup. Test that you can actually decrypt with it — once a year, decrypt one entry from the backup.

Test the restore before you need it. The most common failure is a backup that turns out to be unusable. Restore the exported key into a throwaway GPG home (gpg --homedir /tmp/test-gnupg --import backup.asc) and decrypt one entry. Ten minutes now saves the whole store later.

A health check helps

If you want a quick check of whether your GPG setup is sound, a credential broker can do the inspection for you. trustless runs a doctor command that checks GPG key validity and pass store health — the same check you would do manually, automated — with its commands documented under /docs/commands/. Its setup wizard also generates a GPG key and initializes a pass store when you start from nothing.

If your laptop disappeared tonight, could you decrypt your password store tomorrow morning — or would you be starting from zero?