Clarify gpg.ssh.allowedSignersFile for ssh key signing

[nguyenvulong]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key?platform=linux#telling-git-about-your-ssh-key

What part(s) of the article would you like to see updated?

Telling Git about your SSH key

I believe it should mention adding

gpg.ssh.allowedsignersfile=/path/to/.config/git/allowed_signers

Otherwise, git would complain that

error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification

And in case rules were set, in a project settings > rules > rulesets, github will refuse push

Require signed commits
Commits pushed to matching refs must have verified signatures.

remote: - Commits must have verified signatures.
remote:   Found 1 violation:
remote:
remote:   bd96ff44bfa007357c164fb564b3fdd781b31322
remote:
To github.com:just/a-repo.git
 ! [remote rejected] main -> main (push declined due to repository rule violations)
error: failed to push some refs to 'github.com:just/a-repo.git'

Additional information

Related issue #28577

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@nguyenvulong Thank you for opening an issue! I'll get this triaged for review ✨

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[nguyenalex836]

@nguyenvulong Thank you for your patience while our SME team reviewed! One of our SMEs wanted to relay the following information -

I'm able to ssh sign and push commits without configuring the gpg.ssh.allowedsignersfile. Looking at the remote commits, they are properly flagged as verified. If I run the local command git log --show-signature to view my commit signatures, without the allowedSignersFile configured I do see the errors that they're describing, but these errors don't block me from pushing, and they don't stop the commits from being verified by GitHub. This is because git itself doesn't have the information that it needs to verify the commits locally but GitHub.com has the public key for verification since it's been uploaded to the user's account settings.

The question here is: does lack of local allowedSignersFile stop a user from pushing if they have branch protection rules requiring verified commits? For me, the answer is no - I was able to push just fine. I'm not sure if this is true across all versions of git, though.

One thing to note, if I delete the SSH key from my GitHub account settings, pushing the commit is blocked even after the commit was locally signed.

After adding an allowedsignersfile configuration for myself, I can now locally see that my commits are signed but still can't push unless the public key is linked to my GitHub account from my account settings. So, allowedsignersfile seems to be specifically and only for local signatures and doesn't block push while branch protections for commit signatures are enabled.

Is there possibly anything specific about your OS or git version that's blocking you from pushing if you don't have an allowedsignersfile? It's fine if git show --show-signature shows errors, since we aren't concerned about local commit signatures verification 💛

[github-actions]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See this blog post on bug reports and the importance of repro steps for more information about the kind of information that may be helpful.

[bric3]

For the sake of completeness, I had in my git alias a git log format that was using %G?.

And I started to see these error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification messages, it happened because of the contributor started to use ssh to sign commits.

I also believe that for completeness, this should be at least mentioned as a side effect in the doc.

---

I worked around it with (of course this file being empty, the signature is not known whether it's valid or not (status U))

$ touch ~/.ssh/empty-allowedSignersFile
$ git config --global gpg.ssh.allowedSignersFile ~/.ssh/empty-allowedSignersFile

[nguyenalex836]

@bric3 Thank you for sharing input on this! ✨

I also believe that for completeness, this should be at least mentioned as a side effect in the doc.

Given the age of this issue, would you be willing to open a new one in this repo that also includes what you would propose adding to highlight this side effect? 💛

[TimRudy]

Hi, I would participate by opening an issue with description, but I'm just a newbie who came across this.

Using these pages:
   managing-commit-signature-verification/signing-commits
   managing-commit-signature-verification/telling-git-about-your-signing-key

I didn't seem to have a signed commit - i.e. "No signature"!!! below.
I failed to notice the error at the top. (The red hilight is why my attention was not drawn to it, at all - numerous times.)
Subsequently when I did the touch and empty-allowedSignersFile trick above, I get the more honest message, second example below.

I show second example with the commit I did locally, and next commit is remote commit.

1. "No principal matched." is not too great. I hope not to see that.
2. "gpg: Can't check signature: No public key" for the commit in remote which is perfectly valid and it's signed. You guys sure that key-signing is a nice system? I need to go to GitHub to see "Verified" etc., OK. But maybe the "Can't check signature" message should go away, or should turn it into something more informational with a URL, for good user experience.
3. But obviously my main complaint is:
   a. As a first time commit-signer, I want reassurance locally that it worked, I shouldn't need to push to find out.
   b. The docs didn't mention gpg.ssh.allowedSignersFile and I need to go Google that now.

---

$ git log --show-signature
error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification
commit 87001e69 (HEAD -> PR863)
No signature                                               <-- red hilight
Author: TimRudy <[email protected]>
Date:   Thu Jan 30 17:31:16 2025 -0500

---

---

$ git log --show-signature
commit 87001e69 (HEAD -> PR863)
Good "git" signature with ED25519 key SHA256:jE7AwT...    <-- red hilight
No principal matched.                                     <--
Author: TimRudy <[email protected]>
Date:   Thu Jan 30 17:31:16 2025 -0500

    Fix launch task for Windows

commit 2886ebad (upstream/develop, upstream/HEAD, origin/develop, origin/HEAD, develop)
gpg: Signature made Thu Jan 30 12:34:08 2025 EST          <-- red hilight
gpg:                using RSA key F620B4                  <--
gpg: Can't check signature: No public key                 <--
Merge: 8ea95e65 b3b2f6c4
Author: Rst <[email protected]>
Date:   Thu Jan 30 06:51:27 2025 +0100

---

[Noeurn1]

Believers