gitvaulty
Browse documentation
Command reference

gitvaulty registry upgrade

Inspect or explicitly upgrade an older recipient registry to the current signed-policy format. Ordinary GitVaulty commands preserve the repository's existing registry version.

View source ↗

Inspect or explicitly upgrade an older recipient registry to the current signed-policy format. Ordinary GitVaulty commands preserve the repository's existing registry version.

Read-only preflight

npx gitvaulty registry upgrade --check --actor <username> \
  --identity '<username>=<age-recipient>,<signing-key>'

Repeat --identity for each legacy user whose replacement v4 public identity is not the actor's current GitVaulty master identity. Each user can obtain the two safe-to-share values with gitvaulty key public:

Age recipient: age1...
Signing key: ed25519:...

The preflight reports blockers and the number of files whose recipient set will change. It does not write the registry, SOPS configuration, ciphertext, or Git state.

An upgrade is ready only when:

  • the actor is an existing legacy user and their current master identity matches that username;
  • every legacy username has one valid, unique replacement age recipient and signing key;
  • the actor already belongs to every group, so they can sign each initial v4 policy;
  • the actor already has access to every registered file; and
  • every registered ciphertext decrypts successfully with the actor's registered legacy identity.

These restrictions keep migration from inventing access or policy authority. Resolve any reported blocker in registry v3 before upgrading.

Perform the upgrade

Remove --check after the preflight is ready:

npx gitvaulty registry upgrade --actor alice \
  --identity 'bob=age1...,ed25519:...' \
  --identity 'sam=age1...,ed25519:...'

Interactive use asks for confirmation and defaults to cancel. Automation must add --yes explicitly. GitVaulty converts each group to an actor-signed genesis policy, updates every user's public identity, re-encrypts affected files, and decrypts them again to verify the original bytes. If any step fails, it restores the original registry, SOPS configuration, and ciphertext snapshots.

Review and commit .gitvaulty/recipients.json, .sops.yaml, and all changed *.gitvaulty files together. The command does not stage or commit them.

Compatibility behavior

Registry v3 remains supported indefinitely and is never upgraded by init, an editor, or another command. A clone receives one non-blocking reminder that the optional migration exists. Capabilities that require signed v4 policies, such as group manager changes, return a targeted error without changing repository files. Unknown future registry versions fail closed because the current client cannot safely interpret their access policy.