GitHub sync setup

GitHub is not the password manager. It is only the storage location for encrypted vault files that GitVault creates after local encryption.

Visual checkpoint

Before opening GitVault on another device, Settings should show GitHub Sync as connected and a successful sync timestamp or status.

How GitHub is used

GitVault reads and writes encrypted vault data in your private repository. Passwords, notes, TOTP secrets, recovery records, and device registry data are encrypted before they are uploaded.

Create private storage

1. 1
   Create an empty private repository.

   Use a normal GitHub account. Keep the repository private and dedicated to GitVault.

2. 2
   Leave normal branch settings.

   GitVault only needs repository contents access. You do not need GitHub Pages, Actions, or a public repository for vault sync.

3. 3
   Copy the owner and repository name.

   You will enter both values in GitVault Settings.

Token permissions

1. 1
   Open GitHub fine-grained tokens.

   Go to Developer settings, then Personal access tokens, then Fine-grained tokens.

2. 2
   Select only the vault repository.

   A token scoped to one repository limits damage if the token is exposed.

3. 3
   Grant Metadata read.

   GitHub usually selects this automatically.

4. 4
   Grant Contents read and write.

   This lets GitVault download encrypted data and upload encrypted updates.

5. 5
   Copy the token immediately.

   GitHub shows it once. Paste it into GitVault before closing the page.

Connect GitVault

1. 1
   Unlock GitVault.

   Open Settings after the vault is unlocked.

2. 2
   Open GitHub Sync.

   Enter GitHub owner, repository name, and the fine-grained token.

3. 3
   Save and run sync.

   Wait for success before adding another device.

4. 4
   Check the repository.

   You should see encrypted vault files, not readable secret values.

Rotate a token

1. 1
   Create a replacement token first.

   Use the same repository and permissions.

2. 2
   Update GitVault Settings.

   Paste the new token and confirm sync works.

3. 3
   Revoke the old token in GitHub.

   Do this after GitVault confirms a successful sync with the new token.