Git에서 GPG로 커밋 서명하기

개요

Git 커밋에 GPG 디지털 서명을 추가하면 커밋 작성자의 신원을 증명하고 코드 무결성을 보장할 수 있습니다.

이 문서에서는 GPG의 개념과 Git에서의 활용 방법을 소개합니다.

GPG 키 생성부터 Git 설정, GitHub 연동까지 전체 과정을 단계별로 안내합니다.

GPG란?

GPG(GNU Privacy Guard)는 데이터 암호화와 디지털 서명을 위한 오픈 소스 암호화 소프트웨어입니다.

PGP(Pretty Good Privacy) 표준을 따르며 공개키 암호화 방식을 사용합니다.

주요 특징

• 공개키 암호화: 공개키와 개인키 쌍으로 데이터를 암호화하고 복호화합니다.
• 디지털 서명: 개인키로 데이터에 서명합니다. 작성자 신원과 데이터 무결성을 보장합니다.
• 보안 통신: 이메일과 파일 등을 안전하게 암호화해 전송할 수 있습니다.

Git과 GPG

Git에서 GPG는 커밋과 태그에 디지털 서명을 추가할 때 사용합니다.

• 커밋이 실제로 본인에 의해 작성되었음을 증명할 수 있습니다.
• GitHub와 GitLab 같은 플랫폼에서 Verified 배지를 표시해 신뢰성을 높입니다.
• 코드 변조와 위조를 방지해 프로젝트 보안을 강화합니다.
• 파일을 암호화하여 보호합니다

Git 커밋을 왜 서명하나요?

Git 커밋 작성자 정보는 git config user.name과 user.email로 누구나 임의 설정이 가능합니다.

따라서 이름과 이메일만으로는 실제 작성자를 신뢰하기 어렵습니다.

커밋 전에 개인키로 커밋에 서명하고 공개키를 GitHub 같은 저장소에 등록하면 플랫폼이 서명을 검증해 커밋 작성자 일치 여부를 확인할 수 있습니다.

GPG 사용하기

gnupg 설치

gnupg : GPG 를 사용하기 위한 패키지 설치 (예: mac)

1brew install gnupg

키 생성

gpg --full-generate-key는 대화형 모드로 기본 동작합니다. 배치 모드도 옵션으로 지원합니다.

1gpg --full-generate-key

Please select what kind of key you want:
(1) RSA and RSA
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
(9) ECC (sign and encrypt) default
(10) ECC (sign only)
(14) Existing key from card
Your selection? 1

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096

Requested keysize is 4096 bits Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) 1y

Key is valid for? (0) 1y Key expires at 2027년 2월 16일 화요일 17시 14분 10초 KST Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: your name Email address: your [email protected] Not a valid email address Email address: [email protected] Comment: test You selected this USER-ID: “your name (test) [email protected]”

키 생성 확인

1# 개인키 목록
2gpg --list-secret-keys
3
4# 공개키 목록
5gpg --list-keys

기타 필요한 기능

1# 개인키 삭제
2gpg --delete-secret-keys {sec uuid}
3
4# 공개키 삭제
5gpg --delete-keys {pub uuid}

1# 개인키 내보내기
2# gpg --armor --export-secret-keys {key_id} > private.asc
3gpg --armor --export-secret-keys 7XXXXXXXXXXXXXXXX6 > private.asc
4
5# 공개키 내보내기
6# gpg --armor --export {key_id} > public.asc
7gpg --armor --export 7XXXXXXXXXXXXXXXX6 > public.asc

1# 
2gpg --import private.asc
3
4# trust 지정 
5# gpg --edit-key {key_id}
6gpg --edit-key 7XXXXXXXXXXXXXXXX6
7
8# 등록 확인
9gpg --list-secret-keys --keyid-format LONG

(참고) 트러블슈팅

Git 서명

커밋을 할 때는 GitHub에 등록한 GPG 공개키와 연결된 개인키로 서명해야 합니다.

나중에 Github는 서명된 커밋이 푸시되면 커밋 작성자를 검증합니다.

Github 커밋에 “Verified” 배지도 함께 표시됩니다.

Git에서 GPG 서명 준비

아래 A,B,C 방식 중 하나를 선택합니다.

옵션 A) 수동 서명(커밋마다 -S)

1git commit -S -m "Commit message"

옵션 B) 글로벌 자동 서명(모든 저장소)

1# GPG 키 ID 등록(전역)
2git config --global user.signingkey 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6
3
4# 커밋 자동 서명(전역)
5git config --global commit.gpgsign true
6
7# 설정 확인
8git config --show-origin commit.gpgsign

옵션 C) 저장소 단위 자동 서명(특정 저장소만)

 1# 저장소 이동
 2cd /path/to/repo
 3
 4# GPG 키 ID 등록(로컬)
 5git config --local user.signingkey 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6
 6
 7# 커밋 자동 서명(로컬)
 8git config --local commit.gpgsign true
 9
10# 설정 확인
11git config --show-origin commit.gpgsign

GPG로 서명된 커밋 생성

커밋할 때 -S 옵션을 사용해 서명을 추가합니다.

1# 서명된 커밋 생성
2git commit -S -m "커밋 메시지"
3
4# 자동 서명 설정을 했다면
5git commit -m "커밋 메시지"

서명 확인 : 커밋이 제대로 서명되었는지 확인합니다.

1# 커밋 서명 확인
2git log --show-signature
3
4# 또는
5git verify-commit HEAD

(참고) 트러블슈팅

1**error: gpg failed to sign the data:**
2[GNUPG:] KEY_CONSIDERED 7E7DCEBF62463A41ACD992D8D9F62FE2379DF7E6 2
3[GNUPG:] BEGIN_SIGNING H8
4[GNUPG:] PINENTRY_LAUNCHED 42114 curses 1.3.2 - xterm-256color NONE - 501/20 0
5gpg: signing failed: Inappropriate ioctl for device
6[GNUPG:] FAILURE sign 83918950
7gpg: signing failed: Inappropriate ioctl for device
8**fatal: failed to write commit object**

GitHub 서명

GitHub와 GPG

GitHub에 GPG 공개키를 등록하면 커밋 서명을 검증할 수 있습니다.

GitHub는 푸시된 커밋의 서명을 확인할 때 등록된 GPG 공개키를 사용해 서명이 유효한지 검증합니다.

검증이 성공하면 커밋 옆에 “Verified” 배지가 표시되어 해당 커밋이 등록된 키의 소유자가 작성했음을 증명합니다.

이를 통해 다음과 같은 장점을 얻을 수 있습니다:

• 신원 검증: 커밋 작성자가 실제로 본인임을 증명합니다.
• 위변조 방지: 다른 사람이 내 이름으로 커밋을 작성하는 것을 방지합니다.
• 신뢰성 향상: 오픈소스 프로젝트나 팀 협업에서 코드의 출처를 명확히 합니다.

등록 절차

GPG 공개키를 GitHub 개인 설정의 GPG keys 섹션에 등록합니다.

• GitHub에 로그인한 뒤 우측 상단 프로필 아이콘을 클릭합니다.
• Settings를 선택합니다.
• 좌측 사이드바에서 SSH and GPG keys를 클릭합니다.
• GPG keys 섹션에서 New GPG key 버튼을 클릭합니다.
• 공개키 전체 내용을 복사해 입력란에 붙여 넣습니다.
  • -----BEGIN PGP PUBLIC KEY BLOCK-----, -----END PGP PUBLIC KEY BLOCK----- 포함
• Add GPG key 버튼을 클릭해 등록을 완료합니다.

등록이 완료되면 GPG Keys 목록에 새 키가 표시됩니다.

개인 GPG 공개키 조회

1gpg --list-secret-keys --keyid-format LONG

결과

[keyboxd]

—-

pub rsa4096 2026-02-16 [SC] [expires: 2027-02-16] 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6 ← {Key ID} uid [ultimate] Son Won Chul (plzhans’s macbook) [email protected] sub rsa4096 2026-02-16 [E] [expires: 2027-02-16] ← 키 만료일

키 내용을 확인합니다.

1# 키 열람: gpg --armor --export {Key ID}
2gpg --armor --export 7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX6

GitHub GPG 키 등록

저장소 푸시

서명된 커밋을 GitHub에 푸시하면 “Verified” 배지가 표시됩니다.

1git push origin main

서명된 커밋과 태그 확인

관련 글

• GPG로 .env 파일 암호화해서 안전하게 커밋하기
• age 사용법 정리: recipients로 팀 비밀 파일 암호화하고 개인키로 복호화
• git filter-repo로 비밀키·토큰 유출 커밋 히스토리 완전 삭제하기 (강제 푸시·재동기화)