GPG

Tower offers seamless support for GPG. Read on to find out what exactly you can do with GPG in Tower and find a list of Frequently Asked Questions.

What is GPG?

GPG is a collection of tools that allow signing and encrypting of data using asymmetric cryptography (with public / private keys). Git uses GPG to sign and verify commits and tags. With such a signature, you can easily verify that a commit (or tag) was really made by a specific user.

Installing & Configuring GPG

You can download the official GPG binary from the GnuPG website.
After installing GPG on your machine, you need to configure the GPG binary in Tower. Open the Preferences dialog and select it on the "Git Config" tab.

Creating a GPG key

To generate a GPG key pair, open Git Bash and enter the following command:
$ gpg --full-generate-key

During the next steps, you will be asked to configure the key:

Specify the kind of key you want, or press Enter to accept the default value.
Specify the key size you want, or press Enter to accept the default value.
Enter the length of time the key should be valid or press Enter to set the default value. Selecting this option means that the key doesn't expire.
Review your selections and verify that the information is correct.
Enter your user ID information. Make sure that the email address matches the one you use for service account.
Add a secure passphrase.

Next, you can use the following command to list your existing GPG keys:
$ gpg --list-secret-keys --keyid-format=long

The output may look something like this:

/Users/norabalogh/.gnupg/pubring.kbx
------------------------------------

sec   rsa4096/P441957387YE9518 2020-08-03 [SC] [expires: 2024-08-03]
      14B393K8T74J32V6522GS0R9P441957387YE9518
uid                 [ultimate] Nora Balogh <nora@git-tower.com>
ssb   rsa4096/1054FPR1LM74D722 2020-08-03 [E] [expires: 2024-08-03]

To export the key in ASCII armor format, use the following command. Make sure to substitute in the GPG key ID.
In the below example, the GPG key ID is P441957387YE9518:

$ gpg --armor --export P441957387YE9518

Make sure to restart Tower after generating a new GPG key.

What Can You Do With GPG in Tower?

Verifying Signed Commits

Tower indicates directly in its History views if a commit was signed or not. On top of that, you can also see the signature status (green / orange / red) and access additional information through a popover window.

Verifying Signed Tags

Apart from commits, you can also verify the signatures for tags in Tower. Either right-click on the tag in the sidebar or directly click it in one of the commit views.

Setting & Managing Keys

You can easily select / set / switch keys in Tower:

in the global configuration, in Tower's Preferences dialog
in a specific repository, by selecting the "Settings" item in the sidebar of an open repository
in Tower's User Profiles

Signing Commits

You can configure if you want Tower to automatically sign new commits - either just in a certain repository or globally. This is not limited to just committing, but also includes actions like merge, revert, cherry-pick, and rebase.

Signing Tags

Apart from commits, you can also sign tags. The "Create New Tag" dialog contains a checkbox for this.

Frequently Asked Questions

How can I add a GPG key if I have none?

You can do so in the repository settings in the sidebar. Make sure a repository user is configured and select an existing key. You can do the same for the global user in the "Git Config" tab of Tower's Preferences.

I selected "No GPG Key" in the repository settings, but the selection always resets to a key.

A global GPG key may be configured in the Git preferences. This key is effective for the repository and would be used, which is why you are seeing it here. Try also setting the global user GPG key to "No GPG Key" in the Git preferences.

How can I sign tags?

There is a checkbox in the "Create Tag" dialog and the dialogs for finishing release and hotfix branches via git-flow. Your preference is remembered across app launches. Signed tags are annotated tags which require a message.

You can select the key that should be used to sign the tag via the popup button below the checkbox. If a GPG key is configured it is preselected.

How can I sign commits?

Enable signing either in the GPG section of the repository settings or the global git config in the application preferences and make sure you have a GPG key selected. Signing is automatic from there on.

How can I verify commit signatures?

A status indicator appears in the history for each commit that has a signature. You can click on it to view signature details.

How can I verify tag signatures?

There are two ways to show the signature of a tag:
(a) Just click on the tag badge in the history or the detail view
(b) Right-click the tag in the sidebar and choose "Show GPG Signature…"

What do the colors of the status indicator mean?

Green: Signature Good
Yellow: There is an issue with the signature, click the indicator to read a status message in the popover.
Red: Signature Bad

My keys are not shown when clicking the button, why is that?

Make sure you have a GPG binary configured. Restart Tower if the keys still don't show up.

All GPG status indicators in the history are yellow, why is that?

You haven't trusted any of the keys that have been used to sign the commits. This means that verifying the commit leads to status "Unknown Validity". See the next question for a solution.

A / my signature is shown with status "Unknown Validity". How can I change that?

You will need to import the public keys of the signing authors as trusted keys. You can find help on how to do this in the relevant GnuPG documentation section.

A signature is shown without a GPG key fingerprint, why is that?

GPG support in Tower requires Git 2.20 or newer. The options to read the fingerprints from signatures are not available in older versions.

What does "Verify GPG Signatures" in Merge/Pull dialogs do?

Git checks the signature of the tip commit of the commits that should be merged. If the commit does not have a valid signature, the operation is aborted. If there are signatures with unknown validity, you may have to adjust the trust value of the associated public keys via the command line. Make sure that you verify the key with the author of the commit or tag before trusting it.

I use a subkey for signing but it does not appear in the GPG keys menu!

We don't support subkeys at the moment.

Loading the GPG status in the history takes really long. What can I do?

Verifying commits is an expensive operation, because Git has to call gpg --verify for each commit with a signature. You can improve loading times by reducing the maximum number of commits Tower loads in a batch (see the "Number of commits in history" option in the "General" tab of Tower's Preferences).

A likely cause for really long loading times is, that you don't have the associated public key for the GPG signature of some commits and Git / GPG is unable to download them. In this case the verification of the signatures is really slow (you can also verify this on the command line).

To solve this problem you can do one of the following:

Find the commits with yellow status indicator and "Cannot Be Checked" status, copy the key fingerprint and download the public key in GPG Keychain.
Disable "Verify GPG Signatures" in the history view settings