gpg --recv-keys: Fetch Keys From a Keyserver
gpg --recv-keys downloads a public key by ID or fingerprint from a keyserver and imports it.
When you only have a key ID, recv-keys fetches the full key from a keyserver. Pin on the full fingerprint, since key IDs alone are not safe to trust.
What it does
gpg --recv-keys contacts the keyserver named by --keyserver and imports the public key matching each given ID or fingerprint. It only fetches public keys; secret keys never live on keyservers.
Common usage
gpg --keyserver hkps://keys.openpgp.org \
--recv-keys 0xABCD1234ABCD1234
# refresh keys already in the keyring
gpg --keyserver hkps://keyserver.ubuntu.com --refresh-keys
# fetch via the WKD/auto mechanism for an address
gpg --locate-keys you@example.comOptions
| Flag | What it does |
|---|---|
| --keyserver <url> | Which keyserver to query (hkps://...) |
| --recv-keys <id...> | Fetch and import keys by ID or fingerprint |
| --refresh-keys | Update keys already in the keyring |
| --locate-keys <addr> | Find a key via WKD/DNS/keyserver for an address |
| --keyserver-options <opt> | Tuning, e.g. timeout, no-honor-keyserver-url |
In CI
Keyservers can be slow or unreachable from a runner, so set a timeout via --keyserver-options timeout=10 and have a fallback. Better still, ship the verification key with your repo or as a secret and import it directly, avoiding the network entirely. Always confirm the fetched fingerprint matches what you expect.
Common errors in CI
"gpg: keyserver receive failed: No keyserver available" means no --keyserver is configured or it is unreachable; set one explicitly. "gpg: keyserver receive failed: Server indicated a failure" or a timeout points at a flaky keyserver; retry, switch servers, or import the key locally. "gpg: no valid OpenPGP data found" can mean the ID matched nothing on that server.