GitButler Logo
FeaturesVirtual Branches

Signing Commits

GitHub and GitLab provide a mechanism to verify signed commits using an uploaded public SSH or GPG key. GitButler can be configured automatically sign all your commits.

Git provides a mechanism to sign your commits with a GPG key or SSH key. This enables other developers to make sure that you were actually the person who committed it, rather than someone else just setting their email to yours and committing it as if they were you.

To make this work, a signature is added to the commit header and then that signature is checked against public key stored somewhere, generally for most people the most useful way to verify these signatures is through GitHub or GitLab.

This is what a verified commit looks like on both systems:

Viewing Remote Branches
A verified commit on GitLab.
Viewing Remote Branches
Verified and non-verified commits on GitHub.

This means that the server has a public key that you used to sign the commits that is associated to your account and has verified that this user actually signed this commit.

In order for this to work, you need to:

  1. Tell GitButler to sign your commits
  2. Upload your key as a "signing key" to GitHub or GitLab (or elsewhere)

Telling GitButler to Sign

For GitButler to sign commits, you need to setup Git to sign commits, as we do roughly the same thing that Git itself tries to do, and we read and respect most of the same Git config settings.

The main difference is that instead of commit.gpgSign as the flag that tells Git to automatically sign commits, we look for gitbutler.signCommits. If this is set, GitButler will attempt to sign your commits with the normal Git settings.

We look to see if we have a signing key in user.signingkey. If we have a key, we look for 'ssh' in gpg.format, otherwise we use GPG. We will respect gpg.ssh.program for ssh if there is a different binary path, and gpg.program for GPG. We also identify literal SSH keys in the user.signingkey field.

The only major thing we don't support yet is gpg.ssh.defaultKeyCommand for other ways to get a key other than the user.signingkey field. We also don't support the X.509 smime stuff.

Here is an example, if you have a public key here .ssh/ then you can setup signing with something like this:

$ git config --global user.signingkey "/Users/schacon/.ssh/"
$ git config --global gpg.format ssh
$ git config --global gitbutler.signCommits true

You can also set this up in your project settings, perhaps a little more easily:

Viewing Remote Branches

The nice thing here is that you can also test the settings easily by hitting the "Test Signing" button.

There are lots of other ways to set up GPG or SSH commit signing:

Using GitButler's Generated SSH Key

Earlier versions of GitButler would only sign with it's generated SSH key. Although we've removed that functionality, you can easily set it back up by pointing the signingKey at the generated SSH Key. The key is located in the following locations:

/Users/[username]/Library/Application Support/

Upload Your Signing Key

For GitHub or GitLab to verify your signatures, you need to say that the SSH or GPG public key we are using is a valid signing key for your user.

Adding to GitHub

You can click on the "Add key to GitHub" link in the settings page right about the signing toggle, or you can go here ( to paste that public key in.

Adding a key to GitHub
Be sure to change the type to 'Signing Key'

Now your signed commits should show up as "Verified".

Adding to GitLab

For GitLab you need to go to "SSH Keys" in your profile: and click the "Add new key" button.

Adding a key to GitHub
Add new key here.

Now paste in the public SSH key you copied from GitButler, name it and make sure the "Usage Type" is either "Signing" or "Authentication and Signing".

Adding a key to GitHub
Now all your GitButler generated commits will be verified on that platform!

Last updated on

On this page

Edit on GitHubGive us feedback