Skip to main content

OS Keyring (Recommended)

The OS keyring uses the native operative system's keyring to store the keys securely. This is the recommended and more secure way to store your Gitopia keys.

Typically, an operating system's credential sub-system handles password prompts, private key storage, and user sessions according to the user's password policies. Here is a list of the most popular operating systems and their respective passwords manager:

Follow the steps below to configure git to use your key from OS keyring.

caution

We recommend that you use pass keyring instead of OS keyring for headless environments. OS keyring won't work in headless environment.


Gitopia Wallet

note

This method requires you to know your Gitopia wallet's 24-word mnemonic. If you need help finding your wallet's mnemonic Click here.

  1. Open the Terminal on your computer and add your key to the os keyring using the command given below.
git gitopia keys add <YOUR-KEY-NAME> --recover

Example:

git gitopia keys add gitopia-key --recover

  1. On executing the above command, you will be prompted to enter your wallet mnemonic. Type in your wallet's 24-word recovery phrase and press ENTER.

Your output would look similar to this:

git gitopia keys add gitopia-key --recover
> Enter your bip39 mnemonic
music rose owner spy flight belt belt kitchen wrist axis zebra creek trouble they tool length ...

- address: gitopia1fpsu530cf6ysraxwe68hzvql9v4w0v87rg82qv
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8aBFL62PsLLGc0bIigsaGB4j+YCOOGetf82ENaQ0OOx"}'
type: local

Done

  1. Configure your gitopia key name in git config.
git config --global gitopia.key <YOUR-GITOPIA-KEY-NAME>

Example:

git config --global gitopia.key gitopia-key
note

In macOS, during git push, you will get prompted to enter your user password to access the OS Keyring.

tip

To configure a new key, you need to remove the old gitopia.key from git config and then configure your new key name in git config. You can do this easily by using the below command:

git config --global --unset gitopia.key



Keplr Wallet

note

Users using Keplr wallet to sign in to Gitopia can push repositories to Gitopia only if they have configured git to use their Keplr wallet key from OS Keyring. Unlike Gitopia Wallet Users they cannot use the Gitopia Wallet File method.


1. Finding your Keplr Wallet Mnemonic Seed Phrase

  1. Before moving on to the main steps, you need to find your Keplr wallet Mnemonic Seed Phrase. For this, first, click on the Keplr extension icon on your toolbar to access your account and then click on the account icon as shown in the image.


  1. Now, click on the three dots next to your account name as shown.


  1. In the resulting selection menu, click on View Mnemonic Seed.


  1. You will be asked to type in your wallet password. Once filled, click on Confirm.


  1. Your Keplr wallet Mnemonic Seed Phrase will now be displayed. You will need this mnemonic to set up your key in OS keyring.


  1. Now that you have your mnemonic, the next steps are similar to that of Gitopia wallet. You just need to enter the Keplr wallet Mnemonic Seed Phrase when asked for the mnemonic.

2. Configure git to use your key from OS keyring

  1. Open the Terminal on your computer and add your key to the os keyring using the command given below.
git gitopia keys add <YOUR-KEY-NAME> --recover

Example:

git gitopia keys add gitopia-key --recover

  1. On executing the above command, you will be prompted to enter your wallet mnemonic. Type in your Keplr Wallet Mnemonic Seed Phrase and press ENTER.

Your output would look similar to this:

git gitopia keys add gitopia-key --recover
> Enter your bip39 mnemonic
music rose owner spy flight belt belt kitchen wrist axis zebra creek trouble they tool length ...

- address: gitopia1fpsu530cf6ysraxwe68hzvql9v4w0v87rg82qv
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8aBFL62PsLLGc0bIigsaGB4j+YCOOGetf82ENaQ0OOx"}'
type: local

Done

  1. Configure your gitopia key name in gitconfig.
git config --global gitopia.key <YOUR-GITOPIA-KEY-NAME>

Example:

git config --global gitopia.key gitopia-key
tip

To configure a new key, you need to remove the old gitopia.key from git config and then configure your new key name in git config. You can do this easily by using the below command:

git config --global --unset gitopia.key

Available backends for the keyring

The os backend

The os backend relies on operating system-specific defaults to handle key storage securely. Typically, an operating system's credential sub-system handles password prompts, private keys storage, and user sessions according to the user's password policies. Here is a list of the most popular operating systems and their respective passwords manager:

GNU/Linux distributions that use GNOME as default desktop environment typically come with Seahorse. Users of KDE based distributions are commonly provided with KDE Wallet Manager. Whilst the former is in fact a libsecret convenient frontend, the latter is a kwallet client.

os is the default option since operating system's default credentials managers are designed to meet user's most common needs and provide them with a comfortable experience without compromising on security.

Example:

git gitopia keys add gitopia-key --recover --keyring-backend os
> Enter your bip39 mnemonic
music rose owner spy flight belt belt kitchen wrist axis zebra creek trouble they tool length ...

- address: gitopia1fpsu530cf6ysraxwe68hzvql9v4w0v87rg82qv
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A8aBFL62PsLLGc0bIigsaGB4j+YCOOGetf82ENaQ0OOx"}'
type: local

Done

git config for os keyring:

git config --global gitopia.key gitopia-key
git config --global gitopia.backend os

The pass backend

The pass backend uses the pass utility to manage on-disk encryption of key's sensitive data and metadata. Keys are stored inside gpg encrypted files within app-specific directories. pass is available for the most popular UNIX operating systems as well as GNU/Linux distributions.

Steps to setup keyring with pass backend:

  • Generate a new gpg key without password (it won't work with password)
gpg --full-generate-key
  • Initialize pass keyring with that gpg key (In this example, gitopia is the identifier/name of the gpg key)
pass init gitopia
  • Add your gitopia key to the pass keyring
git gitopia keys add test-key --recover --keyring-backend pass 
  • Verify that the key has been created successfully
git gitopia keys list --keyring-backend pass

git config for pass keyring:

git config --global gitopia.key test-key
git config --global gitopia.backend pass


Basic Key Management

1. Create a new key by seed phrase

git gitopia keys add <YOUR-KEY-NAME> --recover

You can create a new key with the name gitopia-key as in the following example

Example:

git gitopia keys add gitopia-key --recover

2. List your keys

git gitopia keys list

Multiple keys can be created when needed. You can list all keys saved.

git gitopia keys list

Successfully migrated key test.info.
- address: gitopia10vazc96z8g032gqaaaeangd7zsydm5luzaayxt
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+I4HCUY/TJ/x/I7h2Ju64/cYfT/8ZeTRcyvDiCQo6qj"}'
type: local
- address: gitopia1qg7u0mvamw6k6pk9mn9ncxrwnpjdlgt7plapvq
name: test-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"AxfC40EsEdUPeweFgVV9VL8lp0wwK+t46/4NE7lbv9tj"}'
type: local

Done

3. Retrieve key information

git gitopia keys show <YOUR-KEY-NAME>

You can retrieve key information by its name:

git gitopia keys show gitopia-key

- address: gitopia10vazc96z8g032gqaaaeangd7zsydm5luzaayxt
name: gitopia-key
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+I4HCUY/TJ/x/I7h2Ju64/cYfT/8ZeTRcyvDiCQo6qj"}'
type: local

Done

4. Delete a key

git gitopia keys delete <key_name>

You can delete a key by its name.

git gitopia keys delete gitopia-key

Key reference will be deleted. Continue? [y/N]: y
Key deleted forever (uh oh!)
Done