Intall the required tools
gpg needs to be installed.
1
2
gpg --version
sudo apt install gpg
Generating a GPG key
If you don’t already have a GPG key, the following steps can help you get started:
- Install GPG for your operating system.
If your operating system has
gpg2
installed, replacegpg
withgpg2
in the following commands. -
Generate the private/public key pair with the following command, which will spawn a series of questions:
1
gpg --full-gen-key
NOTE: In some cases like Gpg4win on Windows and other macOS versions, the command here may be
gpg --gen-key
. -
The first question is which algorithm can be used. Select the kind you want or press Enter to choose the default (RSA and RSA):
1 2 3 4 5 6
Please select what kind of key you want: (1) RSA and RSA (default) (2) DSA and Elgamal (3) DSA (sign only) (4) RSA (sign only) Your selection? 1
-
The next question is key length. We recommend you choose
4096
:1 2 3
RSA keys may be between 1024 and 4096 bits long. What keysize do you want? (2048) 4096 Requested keysize is 4096 bits
-
Specify the validity period of your key. This is something subjective, and you can use the default value, which is to never expire:
1 2 3 4 5 6 7 8
Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) 0 Key does not expire at all
-
Confirm that the answers you gave were correct by typing
y
:1
Is this correct? (y/N) y
-
Enter your real name, the email address to be associated with this key (should match a verified email address you use in GitLab) and an optional comment (press Enter to skip):
1 2 3 4 5 6 7 8 9
GnuPG needs to construct a user ID to identify your key. Real name: Mr. Robot Email address: <your_email> Comment: You selected this USER-ID: "Mr. Robot <your_email>" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
- Pick a strong password when asked and type it twice to confirm.
-
Use the following command to list the private GPG key you just created:
1
gpg --list-secret-keys --keyid-format LONG <your_email>
Replace
<your_email>
with the email address you entered above. -
Copy the GPG key ID that starts with
sec
. In the following example, that’s30F2B65B9246B6CA
:1 2 3 4
sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA uid [ultimate] Mr. Robot <your_email> ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
-
Export the public key of that ID (replace your key ID from the previous step):
1
gpg --armor --export 30F2B65B9246B6CA
- Finally, copy the public key and add it in your user settings
Importing an existing GPG key
1
gpg --import <keyfile_name>.asc
Adding a GPG key to your Gitlab account
NOTE: After you add a key, you cannot edit it, only remove it. In case the paste didn’t work, you have to remove the offending key and re-add it.
You can add a GPG key in your user settings:
- In the top-right corner, select your avatar.
- Select Edit profile.
- In the left sidebar, select GPG Keys.
- Paste your public key in the Key text box.
- Select Add key to add it to GitLab. You can see the key’s fingerprint, the corresponding email address, and creation date.
Associating your GPG key with Git
After you have created your GPG key and added it to your account, it’s time to tell Git which key to use.
-
Use the following command to list the private GPG key you just created:
1
gpg --list-secret-keys --keyid-format LONG <your_email>
Replace
<your_email>
with the email address you entered above. -
Copy the GPG key ID that starts with
sec
. In the following example, that’s30F2B65B9246B6CA
:1 2 3 4
sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA uid [ultimate] Mr. Robot <your_email> ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
-
Tell Git to use that key to sign the commits:
1
git config --global user.signingkey 30F2B65B9246B6CA
Replace
30F2B65B9246B6CA
with your GPG key ID. -
(Optional) If Git is using
gpg
and you get errors likesecret key not available
orgpg: signing failed: secret key not available
, run the following command to change togpg2
:1
git config --global gpg.program gpg2
Signing commits
After you have created your GPG key and added it to your account, you can start signing your commits:
-
Commit like you used to, the only difference is the addition of the
-S
flag:1
git commit -S -m "My commit msg"
- Enter the passphrase of your GPG key when asked.
- Push to GitLab and check that your commits are verified.
If you don’t want to type the -S
flag every time you commit, you can tell Git
to sign your commits automatically:
1
git config --global commit.gpgsign true
Verifying commits
-
Within a project or merge request, navigate to the Commits tab. Signed commits show a badge containing either Verified or Unverified, depending on the verification status of the GPG signature.
-
By clicking on the GPG badge, details of the signature are displayed.
Revoking a GPG key
Revoking a key unverifies already signed commits. Commits that were verified by using this key changes to an unverified state. Future commits stay unverified after you revoke this key. This action should be used in case your key has been compromised.
To revoke a GPG key:
- In the top-right corner, select your avatar.
- Select Edit profile.
- In the left sidebar, select GPG Keys.
- Select Revoke next to the GPG key you want to delete.
Removing a GPG key
Removing a key does not unverify already signed commits. Commits that were verified by using this key stay verified. Only unpushed commits stay unverified after you remove this key. To unverify already signed commits, you need to revoke the associated GPG key from your account.
To remove a GPG key from your account:
- In the top-right corner, select your avatar.
- Select Edit profile.
- In the left sidebar, select GPG Keys.
- Select the trash icon ({remove}) next to the GPG key you want to delete.
Troubleshooting
If you have trouble after commiting with git and you get an error which looks like this:
1
2
error: gpg failed to sign the data
fatal: failed to write commit object
Then it might help to put the following into your .bashrc
file:
1
2
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc
source ~/.bashrc
Further reading
For more details about GPG, see: