doc/user/project/repository/signed_commits/gpg.md
{{< details >}}
{{< /details >}}
You can sign the commits you make in a GitLab repository with a GPG (GNU Privacy Guard) key.
[!note] GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and implementations.
For GitLab to consider a commit verified:
GitLab uses its own keyring to verify the GPG signature. It does not access any public key server.
GPG verified tags are not supported.
For more details about GPG, refer to the related topics list.
To view a user's public GPG key, you can either:
https://gitlab.example.com/<USERNAME>.gpg. GitLab displays the GPG key,
if the user has configured one, or a blank page for users without a configured GPG key.https://gitlab.example.com/<USERNAME>). In the upper-right corner
of the user's profile, select View public GPG keys ({{< icon name="key" >}}).
This button is shown only if the user has configured the key.To sign commits, you must configure both your local machine and your GitLab account:
If you don't already have a GPG key, create one:
Install GPG for your operating system.
If your operating system has gpg2 installed, replace gpg with gpg2 in
the commands on this page.
To generate your key pair, run the command appropriate for your version of gpg:
# Use this command for the default version of GPG, including
# Gpg4win on Windows, and most macOS versions:
gpg --gen-key
# Use this command for versions of GPG later than 2.1.17:
gpg --full-gen-key
Select the algorithm your key should use, or press <kbd>Enter</kbd> to select
the default option, RSA and RSA.
Select the key length, in bits. GitLab recommends 4096-bit keys.
Specify the validity period of your key. This value is subjective, and the default value is no expiration.
To confirm your answers, enter y.
Enter your name.
Enter your email address. It must match a verified email address in your GitLab account.
Optional. Enter a comment to display in parentheses after your name.
GPG displays the information you've entered so far. Edit the information or press
<kbd>O</kbd> (for Okay) to continue.
Enter a strong password, then enter it again to confirm it.
To list your private GPG key, run this command, replacing
<EMAIL> with the email address you used when you generated the key:
gpg --list-secret-keys --keyid-format LONG <EMAIL>
In the output, identify the sec line, and copy the GPG key ID. It begins after
the / character. In this example, the key ID is 30F2B65B9246B6CA:
sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid [ultimate] Mr. Robot <your_email>
ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
To show the associated public key, run this command, replacing <ID> with the
GPG key ID from the previous step:
gpg --armor --export <ID>
Copy the public key, including the BEGIN PGP PUBLIC KEY BLOCK and
END PGP PUBLIC KEY BLOCK lines. You need this key in the next step.
To add a GPG key to your user settings:
GitLab shows the key's fingerprint, email address, and creation date.
After you add a key, you cannot edit it. Instead, remove the offending key and re-add it.
After you create your GPG key and add it to your account, you must configure Git to use this key:
Run this command to list the private GPG key you just created,
replacing <EMAIL> with the email address for your key:
gpg --list-secret-keys --keyid-format LONG <EMAIL>
Copy the GPG private key ID that starts with sec. In this example, the private key ID is
30F2B65B9246B6CA:
sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid [ultimate] Mr. Robot <your_email>
ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
Run this command to configure Git to sign your commits with your key,
replacing <KEY ID> with your GPG key ID:
git config --global user.signingkey <KEY ID>
After you add your public key to your account, you can sign individual commits manually, or configure Git to default to signed commits:
Sign individual Git commits manually:
Add -S flag to any commit you want to sign:
git commit -S -m "My commit message"
Enter the passphrase of your GPG key when asked.
Push to GitLab and check that your commits are verified.
Sign all Git commits by default by running this command:
git config --global commit.gpgsign true
If you maintain signing keys for separate purposes, such as work and personal
use, use an IncludeIf statement in your .gitconfig file to set which key
you sign commits with.
Prerequisites:
In the same directory as your main ~/.gitconfig file, create a second file,
such as .gitconfig-gitlab.
In your main ~/.gitconfig file, add your Git settings for work in non-GitLab projects.
Append this information to the end of your main ~/.gitconfig file:
# The contents of this file are included only for GitLab.com URLs
[includeIf "hasconfig:remote.*.url:https://gitlab.com/**"]
# Edit this line to point to your alternative configuration file
path = ~/.gitconfig-gitlab
In your alternative .gitconfig-gitlab file, add the configuration overrides to
use when you're committing to a GitLab repository. All settings from your
main ~/.gitconfig file are retained unless you explicitly override them.
In this example,
# Alternative ~/.gitconfig-gitlab file
# These values are used for repositories matching the string 'gitlab.com',
# and override their corresponding values in ~/.gitconfig
[user]
email = [email protected]
signingkey = <KEY ID>
[commit]
gpgsign = true
If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits:
To revoke a GPG key:
When you remove a GPG key from your GitLab account:
To remove a GPG key from your account:
If you must unverify both future and past commits, revoke the associated GPG key instead.
If you receive the errors secret key not available
or gpg: signing failed: secret key not available, try using gpg2 instead of gpg:
git config --global gpg.program gpg2
If your GPG key is password protected and the password entry prompt does not appear,
add export GPG_TTY=$(tty) to your shell's rc file (commonly ~/.bashrc or ~/.zshrc)
If your GPG key is password protected, and you receive one of the following errors:
error: gpg failed to sign the data
fatal: failed to write commit object
gpg: signing failed: Inappropriate ioctl for device
If the password entry prompt doesn't appear:
Open your shell's configuration file, commonly ~/.bashrc or ~/.zshrc, in a text editor.
Add the following line to the file:
export GPG_TTY=$(tty)
Save the file and exit the text editor.
Apply the changes. Choose one of the following:
source ~/.bashrc or source ~/.zshrc.[!note] The exact steps may vary depending on your operating system and shell configuration.