doc/user/project/repository/signed_commits/ssh.md
{{< details >}}
{{< /details >}}
When you sign commits or tags with SSH keys, GitLab uses the SSH public keys associated with your GitLab account to cryptographically verify the signature. If successful, GitLab displays a Verified label on the commit or tag.
For GitLab to consider a commit verified:
If the signature is valid but the committer email does not match a verified email on your account, the commit is marked Unverified.
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.
After you create an SSH key and add it to your GitLab account configure Git to begin using the key.
Prerequisites:
Git 2.34.0 or later.
OpenSSH 8.1 or later.
[!note] OpenSSH 8.7 has broken signing functionality. If you are on OpenSSH 8.7, upgrade to OpenSSH 8.8.
An SSH key with the Usage type Authentication & Signing or Signing.
The following SSH key types are supported:
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
Prerequisites:
user.email matches a verified email address
associated with your GitLab account.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, see verify commits locally.
{{< history >}}
render_ssh_signed_tags_verification_status. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
After you configure Git to sign commits and tags with your SSH key, you can sign your tags:
When you create a Git tag, add the -s flag:
git tag -s v1.1.1 -m "My signed tag"
Push to GitLab and verify your tags are signed with this command:
git tag --verify v1.1.1
Optional. To sign tags automatically without the -s flag, run:
git config --global tag.gpgsign true
You can verify all types of signed commits in the GitLab UI. Commits signed with an SSH key can also be verified locally.
To verify commits locally, create an
allowed signers file
for Git to associate SSH public keys with users.
This example uses ~/.ssh/allowed_signers, but you can specify a different path.
Use the same path in the following steps.
Create an SSH directory:
mkdir -p ~/.ssh
Create an allowed signers file.
touch ~/.ssh/allowed_signers
Configure Git to use the file:
git config gpg.ssh.allowedSignersFile "$HOME/.ssh/allowed_signers"
Add your entry to the allowed signers file. Replace <MY_KEY> with the name of your key.
If you chose a different path in step 1, replace ~/.ssh/allowed_signers with that path:
# 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 contains your email address, key type, and key contents:
[email protected] namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmaTS47vRmsKyLyK1jlIFJn/i8wdGQ3J49LYyIYJ2hv
Repeat this step for each additional user you want to verify. If you collaborate with other contributors, consider checking this file into your Git repository.
Use git log --show-signature to view the signature status for commits:
$ git log --show-signature
commit e2406b6cd8ebe146835ceab67ff4a5a116e09154 (HEAD -> main, origin/main, origin/HEAD)
Good "git" signature for [email protected] with ED25519 key SHA256:Ar44iySGgxic+U6Dph4Z9Rp+KDaix5SFGFawovZLAcc
Author: John Doe <[email protected]>
Date: Tue Nov 29 06:54:15 2022 -0600
SSH signed commit
You can revoke or delete your SSH keys used to sign commits. For more information, see remove an SSH key.
Removing your SSH key can impact any commits signed with the key: