浏览文档

Signing key rotation

The repository key can be replaced without users doing anything, as long as they update at least once while both keys are in use. A rotation has two phases: an overlap, in which everything is signed with the outgoing and the incoming key, and a switch, after which only the incoming key signs.

How clients learn the new key

Every summary lists the public keys of its signing keys in its xa.gpg-keys metadata (publish-repo.sh). On any install or update, and on flatpak remote-modify --update-metadata, a client checks the summary against a key it already trusts and then adds the listed keys to that remote’s keyring. This works for user and system installs (through the system helper, without a password prompt) on every flatpak version tested, 1.12 to 1.16.

Clients only ever add keys this way. The outgoing key stays trusted on every machine that had it, so a rotation moves signing to a new key, but it can’t revoke the old one on existing clients.

Current rotation

Outgoing Incoming
Fingerprint A2A6AE245C8B2FC3A5CCCC5487283E7A6DFC22BC C7907AB1A4C3CF08614A882FCB843F54736642EF
Signing subkey 529EAFA2E08C1B81C4DCEE309FF8BFD0DE21F8E7 5812CEE578948B7A67BCE9B7C189B1A5BFFBEDA7
CI secret (production) FLATPAK_GPG_PRIVATE_KEY FLATPAK_GPG_KEY_2026_11
Created 2026-06-19; its master key was lost, so only the subkey exists 2026-11-15; master backed up offline

The overlap starts with the backfill run below. The switch is no earlier than three months later.

For agents

Starting the overlap

  1. Put the incoming signing subkey in the production environment next to the outgoing one, and import both in the “Import signing subkey” steps of publish.yml and delist-prune.yml. Every key CI imports signs every commit and summary (signing_keys in scripts/lib/common.sh).
  2. Run publish.yml by hand with backfill_signatures checked. It signs the current commit of every published ref with the incoming key, so a client that trusts only the incoming key can install apps nothing has rebuilt. ostree gpg-sign doesn’t deduplicate, so the backfill checks each commit’s signature key IDs first; it can be run again safely.
  3. Check that the edge serves the new signatures. *.commitmeta objects hold the signatures and are now uploaded as revalidating (sync-r2.sh), but older ones carry a one-year immutable header. Cloudflare doesn’t cache that extension by default (cf-cache-status: DYNAMIC on https://dl.flatpark.org/objects/<xx>/<rest>.commitmeta); if a cache rule ever makes it HIT, purge the cache for dl.flatpark.org.
  4. Check that a client that trusts only the incoming key installs and updates.

Switching

  1. Delete the outgoing secret from the production environment. Publishing then signs with the incoming key only, and the summary and the .flatpakrepo and .flatpakref files list only it. No code change is needed.
  2. Once nothing references the old secret’s name any more, clean up the import steps.

What a client that missed the overlap sees

flatpak update doesn’t fail: it warns that it treats the fetch error as non-fatal, says “Nothing to do”, and exits 0, so the apps silently stop updating. flatpak remote-ls flatpark shows the real error (“Can’t check signature: public key not found”). The fix is in troubleshooting.

Testing

tests/key-rotation/run.sh runs a whole rotation in podman, with a server running the real publish scripts and clients on flatpak 1.12, 1.14 and 1.16, user and system installs. Run it after changing anything that signs.

在 GitHub 上编辑此页