git-credential-age

A Git credential helper that keeps your credentials in age-encrypted files on disk.

This project utilizes the rust implementation of age: rage

Motivation

Git comes with two built-in credential store: store (in-plaintext) and cache (in-memory), neither of which fits my use case. Storing git credentials in the OS-native keychain used to be my goto.

However, because I work across Windows, Mac, and Linux; relying on native keychain meant maintaining three different .gitconfig. I wanted a single .gitconfig I can sync and expect to work on any machine I use. This is the main reason why I choose to store credentials in age-encrypted files.

This helper does not obtain credential on its own, so the intended setup is to put this behind a credential-generating helper such as: git-credential-oauth:

Install

cargo install --path .

This puts a git-credential-age binary on your PATH (usually ~/.cargo/bin). Once installed in PATH, you can refer to this helper in .gitconfig as age.

Setup

Generate a key pair:

git-credential-age init

init creates an age identity and its matching recipient. If you already have age keys you'd rather use, you could overwrite the pairs:

• recipients.txt: the age recipients (public keys, one recipient per line) used to encrypt the credentials.
• keys.txt: the age identities (private keys, one identity per line) used to decrypt the credentials.

Configure Git

Git is cleverly designed to support multiple credential helpers. To fill credentials, Git calls each helper in turn until it has the information it needs. git-credential-age is a storage helper, designed to be configured in combination with a credential-generating helper.

To use it as an encrypted store in front of git-credential-oauth:

git config --global --unset-all credential.helper
git config --global --add credential.helper age
git config --global --add credential.helper oauth

Order matters here. age comes first so it can answer from stored credentials; oauth is the fallback that fetches a fresh token when credentials doesn't exist or has expired.

File format

The format is dead simple: it is the git credential format, encrypted. Each combination of host and protocol gets its own file such as https_github.com.age. In its decrypted form, it contains the same key=value lines Git uses in its credential protocol:

protocol=https
host=github.com
username=AzureDiamond
password=hunter2

When more than one account exists for a host, the records are stored one after another, separated by a blank line. The whole file is then age-encrypted (ASCII-armored).