skip to content

What problem does the `--refresh-keys` flag solve, and how does it differ from regenerating metadata with `--write-verification-metadata`?

level: seniorimportance: should knowfreq 28%

answer

  1. --refresh-keys re-fetches PGP keys
  2. fixes stale/expired/rotated keyring
  3. does NOT touch trust entries or checksums
  4. pair with --export-keys to persist
  5. separate CI job from metadata regen

basics

~20 s

--refresh-keys re-fetches PGP public keys from key servers and rebuilds the local keyring without changing your trust entries or checksums. Use it when a signer's key was updated/expired so builds can validate signatures again, without re-recording dependency trust.

solid answer

~40 s

`--refresh-keys` targets the keyring, not the trust file. PGP keys can be rotated, get new subkeys, or expire; when that happens Gradle may fail to validate an otherwise-trusted artifact because its cached keyring is stale. Running `./gradlew <task> --refresh-keys` forces Gradle to re-download the public keys for the trusted key ids from the configured key servers and rebuild the local keyring. It does NOT add new dependencies, recompute checksums, or alter `<trusted-key>`/`<pgp>` trust entries — that's the job of `--write-verification-metadata`. Typical CI use: a scheduled job that runs `--refresh-keys --export-keys` to refresh the committed keyring, separate from the dependency-bumping workflow that regenerates metadata. Keeping these concerns split means a key refresh never silently changes which checksums you trust.

code

bash · 5 lines
bash
# Scheduled CI key-refresh job: re-download trusted public keys and rewrite the keyring
./gradlew help --refresh-keys --export-keys

# Distinct from the dependency-bump job, which regenerates trust/checksums:
# ./gradlew build --write-verification-metadata pgp,sha256 --export-keys

go deeper

for a junior

Recognize that PGP keys can expire and there's a flag to refresh them, even if not managing it.

for a middle

Explain --refresh-keys re-fetches public keys to fix stale/expired keyrings and doesn't alter checksums.

for a senior

Contrast it cleanly with --write-verification-metadata and justify separate CI jobs for key refresh vs. trust regeneration.

for a principal

Set cadence/ownership for key refresh, ensure refresh can't smuggle trust changes, and define review gates distinguishing keyring-only vs. trust diffs.

## Why keys go stale PGP signing keys are not static. A maintainer may: - Rotate to a new key or add subkeys. - Have a key reach its expiry date. - Re-publish key material to keyservers. Your local keyring (`gradle/verification-keyring.*`) is a snapshot taken at export time. When a signer's key material changes, Gradle can fail to verify an artifact it should trust — the trust id is right, but the cached public key is outdated/expired. ## What --refresh-keys does ```bash ./gradlew help --refresh-keys ``` It ignores the cached keyring/key data and **re-fetches the public keys** for your trusted key ids from the configured key servers, refreshing what Gradle holds. Pair it with `--export-keys` to also rewrite the committed keyring file: ```bash ./gradlew help --refresh-keys --export-keys ``` It does **not**: - add or remove dependencies, - compute or change checksums, - modify `<trusted-key>` / per-artifact `<pgp>` entries. ## Contrast with --write-verification-metadata | Concern | `--write-verification-metadata` | `--refresh-keys` | |---|---|---| | Adds new dependency checksums | yes | no | | Records/updates trust entries | yes | no | | Re-downloads PGP public keys | no (uses cache) | yes | | Touches the keyring | only with `--export-keys` | refreshes it (with `--export-keys` to persist) | So: bump a dependency → regenerate metadata; a trusted signer rotated their key → refresh keys. Different triggers, different side effects. ## CI strategy Keep them as separate pipelines: 1. **Dependency-update job** (e.g. when Renovate/Dependabot opens a bump): `--write-verification-metadata pgp,sha256 --export-keys`, human-reviewed because it changes *trust*. 2. **Key-refresh job** (scheduled, e.g. weekly): `--refresh-keys --export-keys`, lower-risk because it only refreshes key *material*, not trust decisions. This separation prevents a routine key refresh from sneaking in a new trusted checksum, and keeps PR diffs meaningful (a keyring-only change vs. a metadata trust change).

  • Does --refresh-keys change which artifacts or keys you trust?
    No. It only re-downloads the public key material for already-trusted key ids and refreshes the keyring. Adding trust (new <trusted-key>/<pgp> entries or new dependency checksums) is done by --write-verification-metadata.
  • Why keep key-refresh and metadata-regeneration as separate CI jobs?
    So a routine key refresh can't silently introduce a new trusted checksum, and so PR diffs stay meaningful — a keyring-only change is low risk, while a metadata change is a reviewable trust decision.

saying these in an interview costs you the question

  • Claiming --refresh-keys re-records dependency checksums.
  • Believing --refresh-keys can add new trusted keys/artifacts on its own.
  • Running it offline and expecting it to work — it needs key servers reachable.

context

resolving links…