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 💛