git credentials

username

Nothing special needs to be done for git to remember the username for repository access, just include it in the clone URL:

git clone https://username@github.com/username/reponame.git

Or add it afterwards using git remote set-url <name> <newurl>, e.g.:

git remote set-url origin https://username@github.com/username/reponame.git

On-disk file storage (encrypted)

  • Download the git-credential-netrc

    helper script and put it somewhere in your $PATH. Note that the filename needs to be what git looks for, so e.g. remove the .perl extension. Make it executable.

  • make a ~/.netrc with the following format:

    machine a_server.corp.com
login a_login
password a_password
protocol https

machine a_server2.corp.com
login a_login2
password a_password2
protocol https

  • create or import a gpg key that has a passphrase

  • encrypt the file with gpg -e -r a_recipient .netrc and then delete the plaintext ~/.netrc

  • tell git to use the encrypted file:

    git config --local credential.helper "netrc -f ~/.netrc.gpg -v"

Now the credential helper will decrypt the ~/.netrc.gpg file asking for the gpg key’s passphrase, and the gpg-agent should store the passphrase from then onwards (e.g. until reboot).

decrypt from the terminal

With modern versions of GPG (since 2.1), it will try to show a pinentry prompt by default. This might result in the following error:

Using GPG to open /home/graham/.netrc.gpg: [gpg --decrypt /home/graham/.netrc.gpg]
gpg: encrypted with 2048-bit RSA key, ID 786569FF6ED67CBA, created 2018-03-05
      "graham lopez <myaddr@email.com>"
gpg: public key decryption failed: Inappropriate ioctl for device
gpg: decryption failed: No secret key
No netrc entries found in /home/graham/.netrc.gpg

This occurs because the credential helper isn’t running through a TTY, so there’s no way to render the prompt. Fix this by telling gpg to use loopback pinentry mode. (Solution described here - add to ~/.gnupg/gpg.conf:

use-agent
pinentry-mode loopback

(NOTE: adding this to ~/.gnupg/gpg.conf could break other usage, so might want to edit the git-credential-netrc script to use gpg --decrypt --pinentry-mode loopback instead.) - add to ~/.gnupg/gpg-agent.conf:

allow-loopback-pinentry

and then restart the gpg-agent with echo RELOADAGENT | gpg-connect-agent

In-memory password caching

On almost all systems, git can cache the password in memory for some amount of time. This is stored either globally in $HOME/.gitconfig or per-repo in /path/to/repo-root/.gitconfig. The following would cache the password for 10 minutes:

[credential]
    helper = cache --timeout=600

This can be set via the command-line with git config [--global] credential.helper 'cache --timeout=600'

Keychain-based password caching

Ubuntu 17.10

Ubuntu with Gnome will have gnome-keyring already installed. Seahorse is also available via apt. So we just need to set up the credential helper for git to talk to gnome-keyring:

apt install libgnome-keyring-dev
cd /usr/share/doc/git/contrib/credential/gnome-keyring
make
chmod 755 git-credential-gnome-keyring
git config --global credential.helper /usr/share/doc/git/contrib/credential/gnome-keyring/git-credential-gnome-keyring

Gentoo (outside of Gnome)

We can use gnome-keyring as a git credential helper outside of Gnome as well. We’ll need X support compiled into dbus

USE=X emerge -av -oneshot dbus

now get the working pieces

emerge -av gnome-keyring libsecret seahorse

and finally set up git to use the credential helper

USE=gnome-keyring emerge -av dev-vcs/git git config --global credential.helper /usr/bin/git-credential-libsecret

make sure the keyring daemon starts with X, so add to ~/.xinitrc

eval $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)

Interacting with the keyring

To see what is in the keychain, use seahorse. Any of the keychains can also be unlocked here.

To unlock from the commandline, use secret-tool. It needs a an attribute/value pair to search on, so to see what these are, open up seahorse and look at the “details” tab of a given entry. For git, the entries typically have the following attributes: “server”, “user”, “protocol”. Server is e.g. “github.com” and protocol is typically “https”. So use secret-tool to unlock the keychain (and see the values) like:

secret-tool search --all --unlock protocol https

secret-tool can be used from the cli to store/retrieve arbitrary strings using arbitrary attribute/value pairs, but I haven’t found a way to add attributes to what the git-credential-libsecret utility automatically adds to the keyring.

I haven’t yet found a way to automatically prompt for unlock at login such as happens with display managers like gdm, lightdm, etc.

OSX keychain

See if the OSX keychain credential helper is already installed git credential-osxkeychain

If it isn’t, OSX may prompt you to install it as part of the Xcode commandline tools. Otherwise, it gets installed as part of the homebrew ‘git’ package.

Set git to use the OSX keychain git config --global credential.helper osxkeychain

use the /Applications/Utilities/Keychain Access.app to verify your password storage.