Set Up SSH Remotes

Libra uses your system SSH client for SSH remotes. Complete the steps below before cloning, fetching, pulling, pushing, listing references, or inspecting a remote over SSH.

1. Check Which Key Libra Will Use

Inside an existing Libra repository, first check whether the remote has a Libra-managed vault key:

libra config list --ssh-keys

For a remote named origin, Libra selects an explicit key in this order:

1. The encrypted vault key at vault.ssh.origin.privkey.
2. A legacy repository key at ~/.libra/ssh-keys/<repo-id>/id_ed25519, when present.
3. No explicit Libra key; your system SSH configuration, agent, and default key files choose the identity.

For the first two choices, Libra passes -i <key> to OpenSSH. Libra does not force IdentitiesOnly, so OpenSSH may also offer identities from your agent or configured IdentityFile entries according to its normal rules. With no explicit Libra key, identity selection is entirely controlled by OpenSSH. A standalone ssh -T check can therefore use a different set or order of identities from a Libra remote command.

If the remote has a vault key, print its public half:

libra config get vault.ssh.origin.pubkey

Register that exact public key with the Git hosting account or repository that owns the remote. A successful standalone ssh -T check does not prove that the explicit key selected by Libra is registered or was the identity accepted by the server.

To create a new Libra-managed key for an existing remote instead, run:

libra config generate-ssh-key --remote origin
libra config get vault.ssh.origin.pubkey

Libra stores the generated private key encrypted in its vault. Upload or paste only the public key printed by the second command.

2. Reuse or Create a System SSH Key

If the repository has neither a vault key nor a legacy key at the path above, inspect your existing system keys:

ls -al ~/.ssh

Look for a public/private pair such as id_ed25519.pub and id_ed25519. If you already have a suitable pair, keep it and continue to Register the public key.

If you need a new key, first choose a filename that does not exist. The following checks both halves of the example pair before generating it:

test ! -e ~/.ssh/id_ed25519_libra &&
test ! -e ~/.ssh/id_ed25519_libra.pub &&
ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519_libra

If either test command fails, choose another filename or use the existing key. Do not approve an overwrite prompt for a key you still need.

Because id_ed25519_libra is not an OpenSSH default filename, persist the choice with a dedicated host alias in ~/.ssh/config. Put this block before any matching Host * block because OpenSSH uses the first value obtained for most settings. For GitHub, use:

Host github-libra
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_libra
  IdentitiesOnly yes
  AddKeysToAgent yes

The alias avoids changing ordinary connections to github.com or keys used for other accounts. Use it in the repository URL, for example git@github-libra:OWNER/REPOSITORY.git; update an existing remote with libra remote set-url origin git@github-libra:OWNER/REPOSITORY.git. Use a distinct alias, hostname, and SSH user for another service. Then protect the directory, config, and private key:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519_libra

On macOS only, you may add UseKeychain yes inside the same Host block. The config preserves which file SSH should try; an encrypted key must still be loaded or unlocked in the agent before a non-interactive Libra command. If you intentionally configure Host github.com with IdentitiesOnly yes instead, that restriction applies to every Git and SSH connection using that hostname.

3. Register the Public Key

Display the public key that will authenticate to the remote:

cat ~/.ssh/id_ed25519_libra.pub

Add the complete .pub value to your Git hosting account as an authentication key, or add it as a repository deploy key when that is the intended access model. Never upload, paste, email, or otherwise share the private file without the .pub suffix.

For GitHub, follow the official instructions for adding a new SSH key to your account. GitHub also provides the complete Connect to GitHub with SSH workflow.

4. Load a System Key into the SSH Agent

Run ssh-add -l first. If it reports The agent has no identities, load the key into the existing agent with ssh-add. If it reports that it cannot connect to an authentication agent, start one in the same shell that will run Libra, then load the key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_libra
ssh-add -l

An agent started this way is exported only to that shell and processes launched from it. Another terminal, desktop app, or IDE will not see its socket unless it inherits the same SSH_AUTH_SOCK; configure that environment or use the platform's persistent agent integration.

On macOS only, you can store the key's passphrase in Apple Keychain:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519_libra

Use the ordinary ssh-add command on Linux and other platforms. If you use a different filename, replace the example path in every command.

5. Verify the Host and Account

For GitHub's normal hostname, test authentication with:

ssh -T git@github.com

If you configured the alias above, test the same identity path with ssh -T github-libra.

Use the SSH user and hostname from your actual remote for another provider. On the first connection, compare the displayed host-key fingerprint with a trusted source from the hosting provider or your administrator before accepting it. Do not disable host-key checking to bypass an unverified fingerprint. GitHub documents its expected flow in Testing your SSH connection.

Confirm that the response identifies the account that should have access to the repository. Authentication to the host can succeed while repository authorization still fails, so also check the account's repository permissions and any required organization authorization.

6. Retry the Libra Command

Libra invokes SSH with BatchMode=yes. It cannot stop to request a private-key passphrase or ask you to trust a new host key. Load or unlock the key in your agent and establish host trust separately before retrying the Libra command.

If Libra still reports public-key authentication failure:

1. Inside an existing Libra repository, run libra config list --ssh-keys again and check the legacy repository-key path above. For an initial clone or URL-only ls-remote outside a repository, inspect ~/.ssh/config and ssh-add -l directly.
2. Confirm that the matching public key, including a Libra vault public key when present, is registered with the correct hosting account or repository.
3. Check ssh-add -l when Libra is expected to fall back to your SSH agent.
4. Confirm that the authenticated account can access the repository named by the remote URL.

For more detail about generating keys and loading the agent, see GitHub's official Generating a new SSH key and adding it to the ssh-agent guide.