Sign commits with GPG keys

Aqua relies on the built-in GPG commit signing feature of Git. To get the best experience, we recommend using a gpg2 package with a graphical interface for handling passphrase prompts.

Configure the environment

Set up GPG support

Do one of the following:
- Download and install the latest GitForWindows version (you'll need version 2.19.2 or later). Pre-configured GPG is part of the package.
  To verify everything is set up correctly, open GitBash, run the gpgconf command and make sure the output is like the following:
  gpg:OpenGPG:/usr/bin/gpg gpg-agent:Private Keys:/usr/bin/gpg-agent scdaemon:Smartcards:/usr/lib/gnupg/scdaemon gpgsm:S/MIME:/usr/bin/gpgsm dirmngr:Network:/usr/bin/dirmngr pinentry:Passphrase Entry:/usr/bin/pinentry
  Make sure the pinentry shows a GUI prompt by running the echo GETPIN | pinentry command.
- Download and install the Gpg4Win package and make sure that git config gpg.program points to the gpg.exe file from the package by doing the following:
  1. Run where.exe gpg.
  2. If the output returns several executables, locate the one from Gpg4Win (by default, the path is C:\Program Files (x86)\GnuPG\bin\gpg.exe.
  3. Run git config --global gpg.program "path/to/gpg/from/Gpg4Win".

Set up GPG support

Do one of the following:
- Download and install GPGTools. Pre-configured GPG is part of the package.
  Make sure that git config gpg.program points to the gpg file from the package (by default, the path is /usr/local/MacGPG2/bin/gpg).
- Download and open Homebrew and run the following command: brew install gnupg pinentry-mac.
  To verify everything is set up correctly, open Terminal, run the gpgconf command and make sure the output is like the following:
  pg:OpenGPG:/usr/local/MacGPG2/bin/gpg gpg-agent:Private Keys:/usr/local/MacGPG2/bin/gpg-agent scdaemon:Smartcards:/usr/local/MacGPG2/libexec/scdaemon gpgsm:S/MIME:/usr/local/MacGPG2/bin/gpgsm dirmngr:Network:/usr/local/MacGPG2/bin/dirmngr pinentry:Passphrase Entry:/usr/local/bin/pinentry
  Make sure the pinentry shows a GUI prompt by running the echo GETPIN | pinentry-mac command.

Set up GPG support

Install gpg2 using a package manager that comes with your Linux distribution. The exact list of package will vary based on the distributive you are using, the most important being gnupg2, gnupg-agent, and a pinentry that shows a GUI prompt.
For example, on Ubuntu/Debian, run sudo apt -y install gnupg2 gnupg-agent pinentry-gnome3.
To verify everything is set up correctly, open the Terminal, run the gpgconf command and make sure the output is like the following:
gpg:OpenPGP:/usr/bin/gpg gpg-agent:Private Keys:/usr/bin/gpg-agent scdaemon:Smartcards:/usr/lib/gnupg/scdaemon gpgsm:S/MIME:/usr/bin/gpgsm dirmngr:Network:/usr/bin/dirmngr pinentry:Passphrase Entry:/usr/bin/pinentry
Make sure that the pinentry shows a GUI prompt using the echo GETPIN | pinentry command.

Set up GPG keys

The most secure way is to use smartcards, for example, Yubikey to store the private part of your keys. For more information about setting up Yubikey, refer to YubiKey-Guide.

Import GPG keys

If you already have GPG keys, you need to import them to the respective GPG keyring.

Open Terminal / Command Prompt / GitBash / any other shell you have on your system and run the following command: gpg --import <path to your private gpg.key>

Generate GPG keys

If there are no keys yet, you need to generate a new pair.

Open Terminal / Command Prompt / GitBash / any other shell you have on your system and run the following command: gpg --full-generate-key (for pgp 2.1.17 and below, use the gpg --gen-key command.
Answer the questions that the tool will return. The recommended choices are:
- Type of the key: RSA
- Key size: at least 4096 bits
- Key validity period: 1 year (it's a good practice to rotate the key once a year)
Enter your user ID information. It is recommended to use the same username and e-mail address that is shown as the author of your commits. Specify the GitHub noreply email address if you plan to use the signature along with the email address privacy features.
Enter a secure passphrase. Make sure you enter it in a dialog that should pop up rather than entering it in command line as it is important that GUI is used for such prompts.
Make sure the keys have been imported by running the following command: gpg --list-keys.

Enable commit signing

Start Aqua (or restart it to make sure it loads the changes you've made to your environment).
In the Settings dialog (Ctrl+Alt+S) , go to Version Control | Git, and click the Configure GPG Key button.
In the dialog that opens, click Sign commits with GPG key and select the key you want to use from the list.

Now every commit will be signed with the selected key. The state of the GPG signature will be displayed in the Commit details pane on the Log tab.

Add GPG key to your account

If Git hosting you are using supports verification of GPG signing, upload the public part of your key there.

Follow the instructions for

Last modified: 05 November 2024