출처 대조 B · GitHub 호스티드 ubuntu-latest 러너

검증 환경: GitHub 호스티드 ubuntu-latest 러너 (키 생성·서명·로컬 검증 실행. GitHub 등록과 Verified 표시는 문서 대조)

게시 2026-10-13최종 확인 2026-10-13읽기 6분

Git 커밋 서명을 SSH 키로 설정하기: GitHub Verified 표시

gpg.format ssh, user.signingkey로 Git 커밋을 SSH 키로 서명하고, GitHub에 서명 키를 등록해 Verified 표시를 받는 설정 순서와 로컬 검증 방법.

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: 서명은 있지만 검증하지 못했다.
  • 표시 없음: 서명하지 않은 커밋이다.

원인

서명이 안 붙는 이유는 대개 둘 중 하나다.

  1. Git이 서명 방식을 기본값(GPG)으로 쓰고 있고, 서명 키도 지정하지 않았다.
  2. 서명은 했지만 GitHub 계정에 서명용 키로 등록하지 않았다. 문서에 따르면 SSH 키 등록 화면에서 키 유형은 authentication(SSH로 GitHub에 로그인)과 signing(커밋·태그 서명) 중에서 고른다. 한 키를 두 용도로 쓰려면 두 번 올려야 한다.
로컬에서 gpg.format ssh와 user.signingkey를 설정해 서명하고, GitHub에 Signing Key로 공개 키를 등록하면 Verified가 된다gpg.format ssh 설정user.signingkey에 공개 키 지정git commit으로 서명 생성GitHub에 Signing Key 등록Verified 표시
SSH 서명은 로컬 설정과 GitHub 등록 두 곳이 모두 필요하다 (보라 = 사람 · 파랑 = 자동 · 초록 = 외부)

user.name·user.email 전역 설정은 Git 전역 설정에 있다.

해결 방법

1. SSH 키 준비하기

이미 쓰는 키가 있으면 그대로 써도 된다(공식 문서: 기존 키를 쓰거나 서명 전용 키를 새로 만들 수 있다). 새로 만들 때는 서명 전용 키를 따로 두는 쪽을 권한다. 로그인 키와 용도를 나누면 하나를 폐기해도 다른 쪽이 영향을 받지 않기 때문이다.

Terminal window
ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_signing

비밀번호(passphrase)는 실제 사용 환경에서는 설정하기를 권한다. 아래 「확인」 절의 실행에서는 자동 실행을 위해 빈 값으로 만들었다.

2. Git이 SSH로 서명하게 설정하기

GitHub 문서의 순서 그대로, 서명 방식을 SSH로 바꾸고 공개 키(.pub) 경로를 지정한다.

Terminal window
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519_signing.pub

모든 커밋에 자동으로 서명하려면 다음을 더한다. GitHub의 SSH 안내 절에는 이 줄이 없고, GPG 절에 선택 사항으로 나오는 설정이다.

Terminal window
git config --global commit.gpgsign true

이 설정이 없으면 커밋할 때마다 git commit -S로 서명한다.

3. GitHub에 서명 키로 등록하기

  1. 공개 키 내용을 복사한다(~/.ssh/id_ed25519_signing.pub). 여분의 줄바꿈이나 공백이 붙지 않게 한다.
  2. GitHub 오른쪽 위 프로필 사진 → Settings → SSH and GPG keys.
  3. New SSH key를 누르고 Title을 적는다.
  4. Key type을 Signing Key로 고른다.
  5. 공개 키를 붙여 넣고 Add SSH key를 누른다. 요청이 오면 계정 접근을 확인한다.

로그인 키로 쓰던 키를 서명에도 쓰려면 같은 키를 Authentication Key 유형으로 한 번, Signing Key 유형으로 한 번 등록한다. 서명 키 개수에는 제한이 없다고 문서에 적혀 있다.

이 단계는 GitHub 화면에서 하는 일이라 러너에서 재현하지 않았다. 공식 문서로 대조했다.

4. 서명하고 로컬에서 검증하기

서명된 커밋을 만들고, 서명이 들어갔는지 확인한다.

Terminal window
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" 공개키 형식으로 적는다.

Terminal window
echo "you@example.com namespaces=\"git\" $(cat ~/.ssh/id_ed25519_signing.pub)" > ~/.ssh/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
git verify-commit HEAD

이 파일은 로컬 검증용이다. GitHub의 Verified 판정은 계정에 등록한 서명 키로 GitHub가 한다.

확인

GitHub에서 해당 커밋을 열었을 때 Verified 배지가 보이면 끝이다. 아래는 러너 안에서 새 키와 임시 저장소로 서명·검증 과정을 돌린 기록이다. 수정 전 구간은 검증 파일이 없을 때 git verify-commit이 어떻게 실패하는지 보여 준다.

검증 범위: 키 생성, gpg.format·user.signingkey 설정, 서명 생성, allowedSignersFile을 이용한 로컬 검증은 실행으로 확인했다. GitHub에 키를 등록하는 화면과 Verified 배지는 공식 문서로 대조했다(러너에서는 GitHub 계정을 쓰지 않는다).

CI 실행 결과 · 수정 전 재현 1건 · 수정 후 6/6 단계 성공
검증 환경 4항목
OSUbuntu 24.04.5
Git2.55.0
실행 날짜2026-10-13
작성자 기재 환경GitHub 호스티드 ubuntu-latest 러너 (키 생성·서명·로컬 검증 실행. GitHub 등록과 Verified 표시는 문서 대조)
실행 기록
[PASS] 서명용 ed25519 키 쌍을 만들었다
[PASS] gpg.format이 ssh로 설정됐다
[PASS] user.signingkey가 공개 키 경로다
[PASS] 커밋 객체에 SSH 서명이 들어 있다
수정 전 재현 · 예상된 실패 1건 재현됨수정 전: allowedSignersFile 없이 로컬 검증한다
[XFAIL] allowedSignersFile 없이 git verify-commit — 예상된 실패 재현됨 (/allowedSignersFile needs to be configured/)
    > error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification
수정 후 확인 · 2/2 단계 성공수정 후: allowedSignersFile을 설정했다
[PASS] git verify-commit이 Good signature로 통과한다
[PASS] git log --show-signature에 Good signature가 나온다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • 공개 키 경로를 써야 한다. 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단계처럼 허용 서명자 파일을 만들고 설정한다.

참고 자료