Sign commits with GPG | GitLab (2024)

View a user’s public GPG key
Configure commit signing
- Create a GPG key
- Add a GPG key to your account
- Associate your GPG key with Git
- Sign your Git commits
  - Set signing key conditionally
Revoke a GPG key
Remove a GPG key
Related topics
Troubleshooting
- Secret key not available
- GPG failed to sign the data

Tier: Free, Premium, UltimateOffering: GitLab.com, Self-managed, GitLab Dedicated

You can sign the commits you make in a GitLab repository with aGPG (GNU Privacy Guard) key.

GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material andimplementations.

For GitLab to consider a commit verified:

The committer must have a GPG public/private key pair.
The committer’s public key must be uploaded to their GitLab account.
One of the email addresses in the GPG public key must match a verified email addressused by the committer in GitLab. To keep this address private, use the automatically generatedprivate commit email addressGitLab provides in your profile.
The committer’s email address must match the verified email address from theGPG key.

GitLab uses its own keyring to verify the GPG signature. It does not access anypublic key server.

GPG verified tags are not supported.

For more details about GPG, refer to the related topics list.

View a user’s public GPG key

To view a user’s public GPG key, you can either:

Configure commit signing

To sign commits, you must configure both your local machine and your GitLab account:

Create a GPG key.
Add a GPG key to your account.
Associate your GPG key with Git.
Sign your Git commits.

Create a GPG key

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 inthe 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 Enter to selectthe 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 thedefault value is no expiration.
To confirm your answers, enter y.
Enter your name.
Enter your email address. It must match averified email addressin 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 pressO (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 afterthe / character. In this example, the key ID is 30F2B65B9246B6CA:

sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CAuid [ultimate] Mr. Robot <your_email>ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

To show the associated public key, run this command, replacing <ID> with theGPG key ID from the previous step:
```
gpg --armor --export <ID>
```
Copy the public key, including the BEGIN PGP PUBLIC KEY BLOCK andEND PGP PUBLIC KEY BLOCK lines. You need this key in the next step.

Add a GPG key to your account

To add a GPG key to your user settings:

Sign in to GitLab.
On the left sidebar, select your avatar.
Select Edit profile.
Select GPG Keys ().
Select Add new key.
In Key, paste your public key.
To add the key to your account, select Add key. GitLab shows the key’sfingerprint, email address, and creation date:

After you add a key, you cannot edit it. Instead, remove the offending key and re-add it.

Associate your GPG key with Git

After you create your GPG key andadd it to your account, you must configure Gitto use this key:

Sign your Git commits

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:
1. Add -S flag to any commit you want to sign:
```
git commit -S -m "My commit message"
```
2. Enter the passphrase of your GPG key when asked.
3. 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
```

Set signing key conditionally

If you maintain signing keys for separate purposes, such as work and personaluse, use an IncludeIf statement in your .gitconfig file to set which keyyou sign commits with.

Prerequisites:

Requires Git version 2.13 or later.

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 filepath = ~/.gitconfig-gitlab

In your alternative .gitconfig-gitlab file, add the configuration overrides touse when you’re committing to a GitLab repository. All settings from yourmain ~/.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

Revoke a GPG key

If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits:

Past commits signed by this key are marked as unverified.
Future commits signed by this key are marked as unverified.

To revoke a GPG key:

On the left sidebar, select your avatar.
Select Edit profile.
Select GPG Keys ().
Select Revoke next to the GPG key you want to delete.

Remove a GPG key

When you remove a GPG key from your GitLab account:

Previous commits signed with this key remain verified.
Future commits (including any commits created but not yet pushed) that attemptto use this key are unverified.

To remove a GPG key from your account:

On the left sidebar, select your avatar.
Select Edit profile.
Select GPG Keys ().
Select Remove () next to the GPG key you want to delete.

If you must unverify both future and past commits,revoke the associated GPG key instead.

Configure commit signing for commits made in the web UI
GPG resources:
- Git Tools - Signing Your Work
- Managing OpenPGP Keys
- OpenPGP Best Practices
- Creating a new GPG key with subkeys (advanced)
- Review existing GPG keys in your instance

Troubleshooting

Secret key not available

If you receive the errors secret key not availableor 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)

GPG failed to sign the data

If your GPG key is password protected and you receive the error:

error: gpg failed to sign the datafatal: failed to write commit object

If the password entry prompt does not appear, add export GPG_TTY=$(tty) to your shell’s rc file(commonly ~/.bashrc or ~/.zshrc) and restart your terminal.