누구나 로고
オンライン講座企業・団体研修ライブラリトレンドインサイト無料コースお知らせお問い合わせ採用サイト
취업 자료실Git GPG 서명 오류 완벽 해결 — 'gpg failed to sign' 에러와 Unverified 배지 원인 정리
#Git#GPG#서명#GitHub#오류해결#개발입문

Git GPG 서명 오류 완벽 해결 — 'gpg failed to sign' 에러와 Unverified 배지 원인 정리

2026년 6월 25일 7분 읽기 조회 93

gpg failed to sign the data 에러와 GitHub Unverified 배지, 원인을 다섯 가지로 나눠 정확한 해결 명령어와 함께 정리했습니다. 키 생성부터 GPG_TTY, gpg-agent, Windows Git Bash 경로 설정, 이메일 불일치까지 진단 체크리스트로 확인하세요.

Git GPG 서명 오류 해결 가이드

gpg failed to sign 에러, 당황하지 마세요

Git 커밋에 GPG 서명을 설정한 뒤 처음 git commit을 실행했을 때 "error: gpg failed to sign the data" 라는 빨간 에러 문구를 마주치면 당황스럽습니다. 커밋 자체가 막혀버리기 때문입니다. 또는 커밋은 정상적으로 되었는데 GitHub에서 초록색 Verified 배지 대신 회색 Unverified 배지가 뜨는 경우도 자주 발생합니다.

이 글은 두 문제를 원인별로 정확히 나누고, 각 원인에 맞는 해결 명령어를 그대로 따라 칠 수 있도록 정리했습니다. Linux·macOS·Windows(Git Bash) 환경을 모두 다룹니다.

GPG 서명이란? Verified 배지가 뜨는 원리

GPG(GnuPG)는 비대칭키 암호화 방식을 사용하는 오픈소스 암호화 도구입니다. 개인키(secret key)와 공개키(public key) 한 쌍을 만들어, 커밋을 만들 때 개인키로 서명하고 GitHub에는 공개키만 등록합니다.

  • 커밋을 만들 때 Git이 로컬 gpg-agent에게 서명을 요청합니다.
  • gpg-agent가 개인키로 커밋 메타데이터에 대한 전자서명을 생성해 커밋 객체에 함께 저장합니다.
  • GitHub은 저장소에 push된 커밋의 서명을, 계정에 등록된 공개키로 검증합니다.
  • 검증에 성공하고 커밋 작성자 이메일이 그 키의 소유자 이메일과 일치하면 Verified 배지가 표시됩니다.

즉 Verified 배지는 "이 커밋이 실제로 이 GPG 키를 가진 사람에 의해 만들어졌다"는 것을 암호학적으로 증명하는 표시입니다. 이 흐름 중 어느 단계에서 문제가 생기느냐에 따라 에러 메시지가 달라집니다.

터미널 명령어 입력

gpg failed to sign the data 에러의 주요 원인과 해결법

이 에러는 "서명 자체가 실행되지 못했다"는 뜻입니다. 원인은 크게 다섯 가지로 좁혀집니다. 위에서부터 순서대로 확인하세요.

원인 1. GPG 키를 아직 생성하지 않은 경우

가장 흔한 원인입니다. git config commit.gpgsign true만 켜두고 실제 서명에 쓸 키를 만들지 않은 경우입니다. 아래 명령으로 키를 새로 생성합니다.

gpg --full-generate-key

실행하면 순서대로 다음을 묻습니다.

  • 키 종류: RSA and RSA (default) 선택 (Enter)
  • 키 크기: 4096 입력 (기본 3072보다 안전)
  • 유효 기간: 필요에 맞게 설정, 잘 모르면 1y(1년) 권장 — 만료일을 너무 길게 잡으면 분실 시 위험, 아예 없음(0)으로 하면 만료 관리가 안 됨
  • 이름·이메일: GitHub 계정에 등록되어 있고 verified 상태인 이메일과 정확히 동일하게 입력 (이 부분이 뒤에서 다룰 Unverified 배지 문제의 핵심입니다)
  • 암호(passphrase): 커밋마다 요구될 수 있는 비밀번호, 설정 권장

원인 2. git config에 signingkey가 설정되지 않은 경우

키는 있는데 어떤 키를 쓸지 Git에게 알려주지 않은 경우입니다. 먼저 보유한 키 목록과 키 ID를 확인합니다.

gpg --list-secret-keys --keyid-format=long

출력은 아래와 비슷한 형태입니다.

sec   rsa4096/3AA5C34371567BD2 2024-01-10 [SC] [expires: 2025-01-10]
      42B317FD4BA89E7A2D3390276B4059EF456BF98F
uid                 [ultimate] Hong Gil-dong <hong@example.com>
ssb   rsa4096/4BB6D45482678BE3 2024-01-10 [E]

sec rsa4096/ 뒤에 오는 3AA5C34371567BD2 부분이 키 ID입니다. 이 값을 Git 설정에 등록합니다.

git config --global user.signingkey 3AA5C34371567BD2
git config --global commit.gpgsign true
git config --global tag.gpgsign true

마지막 줄은 태그에도 서명을 적용하는 옵션으로 선택 사항입니다. 현재 설정을 한 번에 점검하려면 다음 명령을 사용합니다.

git config --global --list | grep -i "sign\|gpg"

원인 3. GPG_TTY 환경변수 문제 (Linux·macOS)

키도 있고 signingkey도 설정했는데 여전히 실패한다면, 특히 SSH 원격 접속 환경이나 tmux·VS Code 통합 터미널에서 자주 발생하는 원인입니다. gpg-agent가 비밀번호 입력창(pinentry)을 띄울 터미널을 찾지 못해 나는 에러입니다. 실제 gpg 에러 메시지를 직접 보면 원인이 명확합니다.

echo "test" | gpg --clearsign

이때 gpg: signing failed: Inappropriate ioctl for device 라는 메시지가 뜬다면 GPG_TTY 미설정이 원인입니다. 해결은 현재 터미널이 어떤 tty인지 gpg-agent에게 알려주는 것입니다.

export GPG_TTY=$(tty)

이 명령은 새 터미널을 열 때마다 초기화되므로, 셸 설정 파일에 영구적으로 추가해야 합니다.

# bash 사용자
echo 'export GPG_TTY=$(tty)' >> ~/.bashrc
source ~/.bashrc

# zsh 사용자 (macOS 기본 셸)
echo 'export GPG_TTY=$(tty)' >> ~/.zshrc
source ~/.zshrc

원인 4. gpg-agent가 응답하지 않거나 pinentry 설정 문제

gpg-agent 프로세스가 죽어있거나 이전 세션의 소켓이 꼬여 있으면 서명 요청 자체가 응답 없이 실패합니다. 에이전트를 강제로 재시작합니다.

gpgconf --kill gpg-agent

이후 다시 커밋을 시도하면 에이전트가 새로 뜨면서 pinentry(암호 입력창)가 정상적으로 나타나는 경우가 많습니다. macOS에서 pinentry 창 자체가 뜨지 않는다면 pinentry-mac이 없는 경우이므로 설치 후 경로를 지정합니다.

brew install pinentry-mac
echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

원인 5. Windows(Git Bash) 환경 특이사항

Windows에서는 보통 Gpg4win을 설치해 gpg를 사용합니다. 이 환경에서는 GPG_TTY보다 Git이 gpg 실행 파일 경로를 못 찾는 문제가 더 흔합니다. pinentry는 GUI 팝업으로 뜨기 때문에 GPG_TTY 설정은 대부분 불필요합니다. 먼저 gpg 실행 파일 경로를 확인합니다.

where gpg
gpg --version

경로가 잡히는데도 git이 인식하지 못하면 아래처럼 Git 설정에 절대경로를 직접 지정합니다(Windows 경로도 슬래시(/)로 표기).

git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

설치 위치가 다르면 실제 gpg.exe가 설치된 경로로 바꿔야 합니다. 64비트 Gpg4win은 C:/Program Files/GnuPG/bin/gpg.exe인 경우도 있으니 where gpg 결과를 그대로 쓰는 것이 가장 안전합니다.

보안 및 암호화

원인을 못 찾겠다면: 직접 진단하기

Git이 보여주는 에러 메시지는 뭉뚱그려져 있어 원인 파악이 어렵습니다. gpg를 직접 호출해 진짜 에러를 확인하는 것이 가장 빠른 진단법입니다.

echo "test" | gpg --clearsign

이 명령이 성공하면(서명된 텍스트 블록이 출력되면) GPG 자체는 정상 동작하는 것이므로 문제는 Git 쪽 설정(signingkey, gpg.program 경로)에 있습니다. 실패한다면 GPG_TTY나 에이전트, pinentry 쪽 문제입니다. 커밋이 이미 서명되었는지, 서명이 유효한지는 다음 명령으로 확인합니다.

git log --show-signature -1
git verify-commit HEAD

GitHub에 공개키(GPG Public Key) 등록하기

로컬에서 서명이 정상적으로 되어도 GitHub 계정에 공개키를 등록하지 않으면 검증할 방법이 없어 Unverified로 표시됩니다. 공개키를 텍스트로 추출합니다.

gpg --armor --export 3AA5C34371567BD2

-----BEGIN PGP PUBLIC KEY BLOCK----- 부터 -----END PGP PUBLIC KEY BLOCK-----까지 출력된 전체 텍스트를 복사합니다.

  1. GitHub 우측 상단 프로필 → Settings
  2. 왼쪽 메뉴에서 SSH and GPG keys
  3. New GPG key 클릭
  4. 복사한 공개키 전체를 붙여넣고 Add GPG key 클릭

등록 직후 GitHub이 비밀번호나 2FA 확인을 요구할 수 있습니다. 등록 후에는 이미 push된 과거 커밋도 이메일과 키가 일치하면 소급 적용되어 Verified로 바뀝니다.

커밋은 성공했는데 Unverified 배지가 뜨는 이유

서명 자체는 문제없이 되었는데 GitHub이 인정하지 않는 경우, 아래 세 가지가 거의 전부입니다.

1) 이메일 불일치 (가장 흔함)

커밋 작성자 이메일(git config user.email)이 GPG 키에 등록된 UID의 이메일과 정확히 일치해야 하고, 동시에 그 이메일이 GitHub 계정에서 verified 상태여야 합니다. 셋 중 하나만 어긋나도 Unverified가 뜹니다.

git config --global user.email
gpg --list-secret-keys --keyid-format=long

두 값을 나란히 비교하고, GitHub Settings → Emails에서 해당 이메일이 인증(verified)되어 있는지 확인하세요.

2) 키가 만료됨

GPG 키 생성 시 지정한 유효 기간이 지나면 그 키로 만든 새 커밋은 Unverified로 표시됩니다. 만료일은 아래 명령으로 확인·연장할 수 있습니다.

gpg --list-keys --keyid-format=long
gpg --edit-key 3AA5C34371567BD2

--edit-key 진입 후 expire 명령으로 만료일을 갱신하고 save로 저장합니다. GitHub에도 갱신된 공개키를 다시 등록해야 반영됩니다.

3) 여러 UID 중 하나만 등록된 경우

키 하나에 이메일 UID가 여러 개 붙어 있을 수 있습니다(예: 회사 이메일 + 개인 이메일). 현재 커밋에 사용된 이메일이 그중 GitHub에서 인증된 UID와 일치하는지 확인해야 합니다.

사이버 보안 개념

진단 체크리스트

증상확인할 것해결 명령
gpg failed to sign, 키 자체가 없음gpg --list-secret-keys 결과가 비어있음gpg --full-generate-key
gpg failed to sign, 키는 있음git config user.signingkey 값이 없거나 오타git config --global user.signingkey KEY_ID
Inappropriate ioctl for deviceSSH·tmux·통합터미널 환경export GPG_TTY=$(tty) (rc 파일에 등록)
pinentry 창이 안 뜸 / 응답 없음gpg-agent 프로세스 상태gpgconf --kill gpg-agent
Windows에서 gpg 인식 안 됨gpg.exe 경로git config --global gpg.program "경로"
서명은 되는데 Unverified커밋 이메일 vs 키 UID vs GitHub verified 이메일세 값 모두 일치시키기
Unverified (예전엔 Verified였음)키 만료일gpg --edit-key → expire → 재등록

이런 분께 추천합니다

  • GPG 서명 설정 후 커밋 시 gpg failed to sign the data 에러가 반복되는 분
  • GitHub 커밋에 Unverified 배지가 표시되어 원인을 모르는 분
  • Git 서명 환경을 처음 구성해보는 개발 입문자
  • SSH 원격 서버나 tmux 환경에서만 서명이 실패하는 분
  • Windows Git Bash에서 gpg 연동이 안 되는 분

수강 정보

항목 내용
수강료 무료
강의 수 1강
강의 분류 개발·프로그래밍
강사 누구나패스
수준 입문 (GPG 서명 기초 설정 후 진행 권장)

자주 묻는 질문 (FAQ)

Q. export GPG_TTY=$(tty) 명령어를 매번 입력해야 하나요?

매번 입력하면 번거롭습니다. 셸 설정 파일(~/.bashrc 또는 ~/.zshrc)에 한 번 추가해두면 터미널을 열 때마다 자동으로 적용됩니다. Windows Git Bash나 GUI 환경(pinentry가 팝업으로 뜨는 경우)에서는 이 설정 자체가 필요 없는 경우가 많습니다.

Q. 이메일을 맞게 설정했는데도 Unverified가 뜹니다. 다른 원인이 있나요?

이메일이 정확히 일치해도 GPG 키 자체가 GitHub에 등록되어 있지 않거나, 키가 만료된 경우 Unverified가 표시됩니다. gpg --armor --export로 뽑은 공개키가 GitHub Settings → SSH and GPG keys에 실제로 등록되어 있는지, 그리고 gpg --list-keys로 만료일이 지나지 않았는지 함께 점검하세요.

Q. Windows 환경에서도 같은 방법으로 해결되나요?

키 생성, signingkey 설정, GitHub 등록 절차는 운영체제와 무관하게 동일합니다. 다만 GPG_TTY 트릭은 리눅스·macOS 터미널 특유의 문제이므로 Windows(Git Bash 포함)에서는 대부분 불필요하고, 대신 git config --global gpg.program으로 gpg.exe 경로를 정확히 지정해야 하는 경우가 더 흔합니다.

Q. GPG 서명 대신 더 쉬운 방법은 없나요?

Git 2.34 이상에서는 이미 사용 중인 SSH 키로 커밋에 서명하는 기능(gpg.format ssh)을 지원합니다. 새로 GPG 키를 만들 필요 없이 기존 SSH 키를 재사용할 수 있어 설정이 더 간단하지만, GitHub 조직 정책에 따라 GPG 서명만 허용하는 경우도 있으니 팀 규칙을 먼저 확인하는 것이 좋습니다.

에러는 누구나 겪습니다. 위 다섯 가지 원인 안에서 순서대로 좁혀가면 대부분 5분 안에 해결됩니다.

강의 자세히 보기 →

#Git#GPG#서명#GitHub#오류해결#개발입문

댓글

0/1000

불러오는 중...

자료실 목록으로

이 글 정보

읽기 시간
7분
조회수
93
게시일
6월 25일

관련 글

  • MCP와 Claude Code로 개발 생산성 200% 올리는 법 — GitHub·Playwright 연동 가이드

    2분

  • 깃허브 입문 가이드 — 개발자 필수 협업 툴

    깃허브 입문 가이드 — 개발자 필수 협업 툴

    5분

  • AI가 짜준 코드, 화면이 깨졌을 때 — 비전공자를 위한 깃 & 깃허브 입문 가이드

    8분

관련 글

MCP와 Claude Code로 개발 생산성 200% 올리는 법 — GitHub·Playwright 연동 가이드

2분 읽기

깃허브 입문 가이드 — 개발자 필수 협업 툴

깃허브 입문 가이드 — 개발자 필수 협업 툴

5분 읽기

AI가 짜준 코드, 화면이 깨졌을 때 — 비전공자를 위한 깃 & 깃허브 입문 가이드

8분 읽기

カスタマーサポート

  • お知らせ
  • よくある質問
  • お問い合わせ
  • コミュニティ

ご利用案内

  • 利用規約
  • プライバシーポリシー
  • 返金ポリシー

サービス

  • 会社紹介
  • 新規登録
  • 新着コース
  • 無料コース
누구나 로고
利用規約プライバシーポリシー返金ポリシー

상호명: NUGUNA  |  대표자: 정우진  |  사업자등록번호: 392-32-01817  |  통신판매업신고: 제 2026-서울양천-0564 호

주소: 서울특별시 양천구 목동서로 100  |  이메일: nugunapass@gmail.com  |  전화: 010-6395-3043

© 2026 NUGUNA. All rights reserved.

KB예금주인증관리자
ホームコースライブラリお問い合わせMY