- Configure Git to sign commits with your SSH key
- Sign commits with your SSH key
- Verify commits
- Revoke an SSH key for signing commits
- Related topics
Sign commits with SSH keys
-
Introduced in GitLab 15.7 with a flag named
ssh_commit_signatures
. Enabled by default. -
Generally available in GitLab 15.8. Feature flag
ssh_commit_signatures
removed.
When you sign commits with SSH keys, GitLab uses the SSH public keys associated with your GitLab account to cryptographically verify the commit signature. If successful, GitLab displays a Verified label on the commit.
You may use the same SSH keys for git+ssh
authentication to GitLab
and signing commit signatures as long as their usage type is Authentication & Signing.
It can be verified on the page for adding an SSH key to your GitLab account.
For more information about managing the SSH keys associated with your GitLab account, see Use SSH keys to communicate with GitLab.
Configure Git to sign commits with your SSH key
After you create an SSH key and add it to your GitLab account or generate it using a password manager, configure Git to begin using the key.
Prerequisites:
- Git 2.34.0 or newer.
-
OpenSSH 8.0 or newer.
OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8. - A SSH key with the usage type of either Authentication & Signing or Signing. The SSH key must be one of these types:
To configure Git to use your key:
-
Configure Git to use SSH for commit signing:
git config --global gpg.format ssh
-
Specify which public SSH key to use as the signing key and change the filename (
~/.ssh/examplekey.pub
) to the location of your key. The filename might differ, depending on how you generated your key:git config --global user.signingkey ~/.ssh/examplekey.pub
Sign commits with your SSH key
Prerequisites:
- You’ve created an SSH key.
- You’ve added the key to your GitLab account.
- You’ve configured Git to sign commits with your SSH key.
To sign a commit:
-
Use the
-S
flag when signing your commits:git commit -S -m "My commit msg"
-
Optional. If you don’t want to type the
-S
flag every time you commit, tell Git to sign your commits automatically:git config --global commit.gpgsign true
- If your SSH key is protected, Git prompts you to enter your passphrase.
- Push to GitLab.
- Check that your commits are verified.
Signature verification uses the
allowed_signers
file to associate emails and SSH keys. For help configuring this file, read Verify commits locally.
Verify commits
You can verify all types of signed commits in the GitLab UI. Commits signed with an SSH key can also be verified locally.
Verify commits locally
To verify commits locally, create an allowed signers file for Git to associate SSH public keys with users:
-
Create an allowed signers file:
touch allowed_signers
-
Configure the
allowed_signers
file in Git:git config gpg.ssh.allowedSignersFile "$(pwd)/allowed_signers"
-
Add your entry to the allowed signers file. Use this command to add your email address and public SSH key to the
allowed_signers
file. Replace<MY_KEY>
with the name of your key, and~/.ssh/allowed_signers
with the location of your project’sallowed_signers
file:# Modify this line to meet your needs. # Declaring the `git` namespace helps prevent cross-protocol attacks. echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/<MY_KEY>.pub)" >> ~/.ssh/allowed_signers
The resulting entry in the
allowed_signers
file contains your email address, key type, and key contents, like this:example@gitlab.com namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv
-
Repeat the previous step for each user who you want to verify signatures for. Consider checking this file in to your Git repository if you want to locally verify signatures for many different contributors.
-
Use
git log --show-signature
to view the signature status for the commits:$ git log --show-signature commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD) Good "git" signature for johndoe@example.com with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc Author: John Doe <johndoe@example.com> Date: Tue Nov 29 06:54:15 2022 -0600 SSH signed commit
Revoke an SSH key for signing commits
Introduced in GitLab 15.9.
If an SSH 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 an SSH key:
- On the left sidebar, select your avatar.
- Select Edit profile.
- On the left sidebar, select () SSH Keys.
- Select Revoke next to the SSH key you want to delete.