Setting Up Git Identities

Working on many projects across multiple identities can be difficult to manage. This is a procedure for leveraging git aliases to set an identity at the project level for any project with support for GPG-based commit signing.

First, remove any existing global identity

git config --global --unset
git config --global --unset
git config --global --unset user.signingkey

Require local config to exist in order to make commits

Without the global user name and user email, git would use the system’s hostname and username to make commits. Tell git to throw an error instead, requiring you to specify an identity for every new project.

git config --global user.useConfigOnly true

For each identity, generate GPG keys

Generate a GPG public/private key pair:

# Newer versions of GPG
gpg --full-gen-key

# Older versions of GPG (< 2.1.17)
gpg --gen-key

Choose (1) RSA and RSA key type. Choose key size of 4096 bits, or whatever you think is appropriate for your use case. Set the key to not expire (0) unless you want to repeat this step periodically. Finally, set your name and email address. Comment can be left blank.

GPG key generation output

Once the key pair is generated we need to export the public key.

Export the public keys

For each identity, export the public key:

gpg --list-secret-keys --keyid-format LONG

where is the email address of the identity you just created.

This will output a sec ID in the format of rsa4096/[serial]. Copy the serial number, then run this command to output the public key:

gpg --armor --export [serial]

Copy the public key block and add it to your Github or Gitlab settings. With the public key, Github and Gitlab can cryptographically verify your commits, placing a “Verified” label next to each. You may also want to enable Vigilant Mode, which will place an “Unverified” label next to commits that have not been signed (otherwise no label will be shown.)

GPG key export

Set global git config identities

Now we need to create the identities in git’s global config. For example:

git config --global "Your Name"
git config --global ""
git config --global user.gitlab.signingkey 543166183AE7043A
git config --global "Your Name"
git config --global ""
git config --global user.github.signingkey BCF8B7A8C138D16B
git config --global "Your Name"
git config --global ""
git config --global user.identity3.signingkey 4F3FFC37B1A027BD
git config --global "Your Name"
git config --global ""
git config --global user.identity4.signingkey D921F8BA473CF1FC

Create git alias

Setting a git alias will give us a new git command to use to set the identity at a project level. This really is just a script that sets a particular global identity to the local config.

git config --global alias.identity '! git config "$(git config user.$"; git config "$(git config user.$"; git config user.signingkey "$(git config user.$1.signingkey)"; :'

Sign all commits by default

To sign a commit, you need to pass the -S flag. It’s easy to forget to do this, so you may want to sign all commits by default.

git config --global commit.gpgsign true

Specify git identity

For each project, specify the git identity to use:

$ cd /path/to/git/repo
$ git config # should be no response
$ git config
$ git identity github
$ git config

That’s it! Now whenever you start a new project or work on an existing project, you can be confident that the correct name, email address, and GPG signing key are being used.