Commit & Tag Signing

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

What is Commit and Tag Signing?

When you sign a commit, you use your cryptographic key (usually a GPG key or an SSH key) to create a digital signature for the commit. This signature is unique to the commit/tag and is generated using your private key. Anyone with your public key can then verify that the commit/tag was indeed made by you and hasn't been tampered with since it was signed.

Git uses GPG or SSH 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.

What Can You Do With GPG & SSH Signing in Tower?

Verifying Signed Commits

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

Verifying Signed Tags

Aside from commits, you can also verify the signatures for tags in Tower. Either right-click on the tag in the sidebar or directly click on 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

In addition to commits, you can also sign tags. The "Create New Tag" dialog contains a checkbox for this.

Installing & Configuring GPG

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

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

Installing and Configuring SSH Signing

In order to be able to sign and verify commits, you need to use an SSH Agent.

System SSH Agent

macOS comes with OpenSSH pre-installed, which includes the ssh-agent utility for managing SSH keys. Tower will automatically know about the System SSH Agent and can make use of it.

For creating SSH keys using the default agent, we recommend reading our Setting Up SSH for Commit Signing blog post.

1Password SSH Agent

Tower provides seamless integration with 1Password, a popular password manager application, which also supports managing your SSH keys and using them for authenticating SSH remote connections and SSH commit signing.

Follow the steps from 1Password SSH Integration to integrate SSH signing using 1Password into Tower.

SSH signature verifying and allowed signers file

Git will only be able to validate SSH signed commits if there is an allowed-signers file configured that contains the public key information of trusted signers (otherwise verifying SSH signed commits will fail without this file). You can place this file anywhere you prefer, but we suggest storing it under the /Users/username/.ssh/ folder.

Multiple keys can be added in an allowed signers file, each on its own line, in the following format:

<comment> <ssh_type> <public_key>

Where:

• comment: An optional comment that can be added for identification purposes. It is typically used to indicate the owner of the key or any other relevant information.
• ssh_type: Specifies the type of the public key. Common types include ssh-rsa, ssh-dss, ssh-ed25519, or ecdsa-sha2-nistp256, depending on the algorithm used to generate the key.
• public_key: Represents the actual public key. It should be a long string of characters.

Configuration of this file is possible in Tower in the “Git Config” preferences and repository settings.

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 Signing Key" in the repository settings, but the selection always resets to a key.

A global Signing 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 Signing key to "No Signing 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 or an SSH 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 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 GPG keys are not shown when expanding the signing keys list, why is that?

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

My SSH keys are not shown when expanding the signing keys list, why is that?

Make sure your keys are loaded into your SSH Agent.

If you are using the system agent you can check if the SSH keys are added to the agent by running the following command:

ssh-add -L

If there are no keys in your System SSH Agent you can read our Adding Your SSH Keys to the ssh-agent blog post.

My SSH keys are not shown when expanding the signing keys list after a computer restart, why is that?

You need to make sure the keys are added to the SSH Agent at Mac startup.

The System SSH Agent doesn't automatically restart after a reboot or re-login and you need to start the agent and load the keys into the agent again. If you want to make this the default behavior you need to add loading the ssh keys into the agent to your login shell configuration file.

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?

• In case the signature is a GPG signature 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.
• In case the signature is an SSH signature make sure you have properly configured an allowed signers file.

I created an allowed signers file but my SSH commits are still not being validated, why is that?

Make sure the entries in the allowed signers file are in the correct format supported by your SSH Agent.

A GPG 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 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 GPG 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.
If there are SSH signatures with unknown validity, make sure the public keys are added to the configured allowed signers file.

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 Signing 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 a 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.