30초 요약
- Git 2.34 이상이면 GPG 없이 SSH 키로 커밋에 서명할 수 있다. GitHub 문서도 SSH 서명 검증은 Git 2.34 이상에서 된다고 안내한다.
- 로컬 설정은 두 줄이다:
git config --global gpg.format ssh,git config --global user.signingkey <공개 키 경로>. 모든 커밋에 서명하려면commit.gpgsign true를 더한다. - GitHub Settings → SSH and GPG keys에서 같은 공개 키를 Signing Key 유형으로 한 번 더 등록해야 Verified가 붙는다.
- 로컬에서
git verify-commit으로 검증하려면gpg.ssh.allowedSignersFile이 따로 필요하다.
증상/목표
GitHub 커밋 목록에 서명 표시가 없거나, 서명은 하고 싶은데 GPG 키 관리가 부담스러운 상황이다. 이 글은 이미 SSH 키를 쓰고 있거나 새로 만들 수 있다는 전제에서, 그 키로 서명하고 GitHub에서 Verified로 보이게 하는 데까지 다룬다.
GitHub 문서가 설명하는 표시 상태는 다음과 같다.
- Verified: 커밋이 서명됐고 GitHub가 올려 둔 공개 키로 서명을 검증했다.
- Unverified: 서명은 있지만 검증하지 못했다.
- 표시 없음: 서명하지 않은 커밋이다.
원인
서명이 안 붙는 이유는 대개 둘 중 하나다.
- Git이 서명 방식을 기본값(GPG)으로 쓰고 있고, 서명 키도 지정하지 않았다.
- 서명은 했지만 GitHub 계정에 서명용 키로 등록하지 않았다. 문서에 따르면 SSH 키 등록 화면에서 키 유형은 authentication(SSH로 GitHub에 로그인)과 signing(커밋·태그 서명) 중에서 고른다. 한 키를 두 용도로 쓰려면 두 번 올려야 한다.
user.name·user.email 전역 설정은 Git 전역 설정에 있다.
해결 방법
1. SSH 키 준비하기
이미 쓰는 키가 있으면 그대로 써도 된다(공식 문서: 기존 키를 쓰거나 서명 전용 키를 새로 만들 수 있다). 새로 만들 때는 서명 전용 키를 따로 두는 쪽을 권한다. 로그인 키와 용도를 나누면 하나를 폐기해도 다른 쪽이 영향을 받지 않기 때문이다.
ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_signing비밀번호(passphrase)는 실제 사용 환경에서는 설정하기를 권한다. 아래 「확인」 절의 실행에서는 자동 실행을 위해 빈 값으로 만들었다.
2. Git이 SSH로 서명하게 설정하기
GitHub 문서의 순서 그대로, 서명 방식을 SSH로 바꾸고 공개 키(.pub) 경로를 지정한다.
git config --global gpg.format sshgit config --global user.signingkey ~/.ssh/id_ed25519_signing.pub모든 커밋에 자동으로 서명하려면 다음을 더한다. GitHub의 SSH 안내 절에는 이 줄이 없고, GPG 절에 선택 사항으로 나오는 설정이다.
git config --global commit.gpgsign true이 설정이 없으면 커밋할 때마다 git commit -S로 서명한다.
3. GitHub에 서명 키로 등록하기
- 공개 키 내용을 복사한다(
~/.ssh/id_ed25519_signing.pub). 여분의 줄바꿈이나 공백이 붙지 않게 한다. - GitHub 오른쪽 위 프로필 사진 → Settings → SSH and GPG keys.
- New SSH key를 누르고 Title을 적는다.
- Key type을 Signing Key로 고른다.
- 공개 키를 붙여 넣고 Add SSH key를 누른다. 요청이 오면 계정 접근을 확인한다.
로그인 키로 쓰던 키를 서명에도 쓰려면 같은 키를 Authentication Key 유형으로 한 번, Signing Key 유형으로 한 번 등록한다. 서명 키 개수에는 제한이 없다고 문서에 적혀 있다.
이 단계는 GitHub 화면에서 하는 일이라 러너에서 재현하지 않았다. 공식 문서로 대조했다.
4. 서명하고 로컬에서 검증하기
서명된 커밋을 만들고, 서명이 들어갔는지 확인한다.
git commit -S -m "서명 테스트"git cat-file commit HEAD | grep -c "BEGIN SSH SIGNATURE"git verify-commit·git log --show-signature로 로컬에서 검증하려면 어떤 키를 신뢰할지 Git이 알아야 한다. 이를 알려 주는 파일이 gpg.ssh.allowedSignersFile이다. 한 줄에 이메일 namespaces="git" 공개키 형식으로 적는다.
echo "you@example.com namespaces=\"git\" $(cat ~/.ssh/id_ed25519_signing.pub)" > ~/.ssh/allowed_signersgit config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signersgit verify-commit HEAD이 파일은 로컬 검증용이다. GitHub의 Verified 판정은 계정에 등록한 서명 키로 GitHub가 한다.
확인
GitHub에서 해당 커밋을 열었을 때 Verified 배지가 보이면 끝이다. 아래는 러너 안에서 새 키와 임시 저장소로 서명·검증 과정을 돌린 기록이다. 수정 전 구간은 검증 파일이 없을 때 git verify-commit이 어떻게 실패하는지 보여 준다.
검증 범위: 키 생성,
gpg.format·user.signingkey설정, 서명 생성,allowedSignersFile을 이용한 로컬 검증은 실행으로 확인했다. GitHub에 키를 등록하는 화면과 Verified 배지는 공식 문서로 대조했다(러너에서는 GitHub 계정을 쓰지 않는다).
검증 환경 4항목
| OS | Ubuntu 24.04.5 |
|---|---|
| Git | 2.55.0 |
| 실행 날짜 | 2026-10-13 |
| 작성자 기재 환경 | GitHub 호스티드 ubuntu-latest 러너 (키 생성·서명·로컬 검증 실행. GitHub 등록과 Verified 표시는 문서 대조) |
[PASS] 서명용 ed25519 키 쌍을 만들었다 [PASS] gpg.format이 ssh로 설정됐다 [PASS] user.signingkey가 공개 키 경로다 [PASS] 커밋 객체에 SSH 서명이 들어 있다
[XFAIL] allowedSignersFile 없이 git verify-commit — 예상된 실패 재현됨 (/allowedSignersFile needs to be configured/)
> error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification[PASS] git verify-commit이 Good signature로 통과한다 [PASS] git log --show-signature에 Good signature가 나온다
주의
- 공개 키 경로를 써야 한다.
user.signingkey에 비공개 키 대신.pub파일 경로를 준다(GitHub 문서). - Git 2.34 이상이 필요하다. GitHub 문서가 SSH 서명 검증을 Git 2.34 이상으로 안내한다.
git --version으로 확인한다. - 등록 유형을 확인한다. Authentication Key로만 올렸으면 Verified가 붙지 않는다. 서명용으로 따로 올려야 한다.
- Vigilant mode는 기본으로 꺼져 있다. 켜면 서명하지 않은 커밋이 Unverified로 표시되고, 작성자와 커밋한 사람이 다르면 Partially verified가 될 수 있다(GitHub 문서).
- 이미 만든 커밋에 소급해서 서명이 붙지는 않는다. 새 커밋부터 적용된다.
자주 묻는 질문
SSH 서명에도 GPG가 필요한가?
필요 없다. gpg.format ssh로 바꾸면 Git이 SSH 키로 서명하며, GitHub 문서도 SSH 키를 서명 키로 쓰는 방법을 따로 안내한다.
로그인용 SSH 키를 서명에도 쓸 수 있나?
쓸 수 있다. 다만 GitHub에는 같은 키를 Authentication Key와 Signing Key로 각각 한 번씩, 두 번 등록해야 한다.
서명했는데 GitHub에서 Unverified로 나온다.
GitHub 문서 기준으로 Unverified는 서명은 있지만 검증하지 못했다는 뜻이다. 먼저 커밋에 쓴 키가 계정에 Signing Key 유형으로 등록돼 있는지 확인한다.
로컬에서 git verify-commit이 실패한다.
gpg.ssh.allowedSignersFile을 설정하지 않았을 가능성이 높다. 위 4단계처럼 허용 서명자 파일을 만들고 설정한다.
참고 자료
- docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key
- docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
- docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification
- git-scm.com/docs/git-config