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
- Put the incoming signing subkey in the
productionenvironment next to the outgoing one, and import both in the “Import signing subkey” steps ofpublish.ymlanddelist-prune.yml. Every key CI imports signs every commit and summary (signing_keysinscripts/lib/common.sh). - Run
publish.ymlby 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-signdoesn’t deduplicate, so the backfill checks each commit’s signature key IDs first; it can be run again safely. - Check that the edge serves the new signatures.
*.commitmetaobjects 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: DYNAMIConhttps://dl.flatpark.org/objects/<xx>/<rest>.commitmeta); if a cache rule ever makes itHIT, purge the cache fordl.flatpark.org. - Check that a client that trusts only the incoming key installs and updates.
Switching
- Delete the outgoing secret from the
productionenvironment. Publishing then signs with the incoming key only, and the summary and the.flatpakrepoand.flatpakreffiles list only it. No code change is needed. - 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.