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 Frequetly 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

We recommend installing GPG Tools from its website. This ensures a valid configuration that works well with Tower. If you install GPG via homebrew or other ways, you should make sure that you have set up the gpg-agent and pinentry-program helpers correctly. You should also add no-tty and use-agent to ~/.gnupg/gpg.conf if these values are missing there.
After installing GPG on your machine, you need to configure the GPG binary in Tower. Open the Settings dialog and select it on the "Git Config" tab.

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 Settings 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

I have a GPG key but signing fails due to a missing password. What can I do?

The password of the key must be stored in Keychain so that GPG can access it. This works by default if you install GPG tools from the website (https://gpgtools.org). The default installation also configures the pinentry-mac program, which displays a password input dialog if a password is required and provides the option to save it into the Keychain.
~/.gnupg/gpg-agent.conf has a pinentry-program key that is used to specify the location of the pinentry program. The default installation uses /usr/local/MacGPG2/libexec/pinentry-mac.app/Contents/MacOS/pinentry-mac. You can also download this program via homebrew: brew install pinentry-mac. Make sure to configure it in the aforementioned config file.

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 then select "Create GPG Key…" from the GPG Key Popup Button menu. You can do the same for the global user in the "Git Config" tab of Tower's Settings.

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 settings. 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 settings.

I want to create a GPG key but the "Create GPG Key" menu item is disabled.

Tower found a key that matches the email address of your current Git user (either global or repository level). You have to change your Git user email address to one that does not already have an associated GPG key.
You should use GPG Keychain if you need advanced key management features.

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 settings 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

I am colorblind and cannot differentiate the status colors, what can I do?

Turn on the accessibility setting Differentiate without color in System Settings > Accessibility > Display. Tower respects this setting and will draw the bad signature status indicator with a square instead of a circle and the warning signature status with a triangle instead of a circle.

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 can open GPG Keychain, show details for the key and use the context menu to accredit it (by signing it with your private key). Make sure that you verify the key fingerprint with the author of the commit or tag before trusting it.

A signature is shown with status "Cannot Be Checked" and shows no name or avatar, just the key fingerprint and the status. How can I change that?

The commit was signed with a private key and you don't have the associated public key in your keyring. Usually the public key is downloaded automatically in these cases, but it may fail sometimes. You can search for and download the public key in GPG Keychain by using the hash from the popover.
You can add auto-key-retrieve to ~/.gnupg/gpg.conf to enable the automatic behavior.

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 go into GPG Keychain (or the command line) and adjust the trust value of the associated public keys. 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 Settings).

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