GPG로 커밋 및 태그 서명

요약

GPG(GNU Privacy Guard) 키로 GitLab 저장소에서 만드는 커밋에 서명할 수 있습니다. GitLab은 OpenPGP, PGP, GPG 관련 모든 자료 및 구현에 대해 GPG라는 용어를 사용합니다. GitLab이 커밋을 검증됨으로 간주하려면:

GPG(GNU Privacy Guard) 키로 GitLab 저장소에서 만드는 커밋에 서명할 수 있습니다.

GitLab은 OpenPGP, PGP, GPG 관련 모든 자료 및 구현에 대해 GPG라는 용어를 사용합니다.

GitLab이 커밋을 검증됨으로 간주하려면:

커밋 작성자에게 GPG 공개/개인 키 쌍이 있어야 합니다.
커밋 작성자의 공개 키가 GitLab 계정에 업로드되어 있어야 합니다.
GPG 공개 키에 있는 이메일 주소 중 하나가 커밋 작성자가 GitLab에서 사용하는 인증된 이메일 주소와 일치해야 합니다. 이 주소를 비공개로 유지하려면 GitLab이 프로필에서 제공하는 자동 생성된 비공개 커밋 이메일 주소를 사용하세요.
커밋 작성자의 이메일 주소가 GPG 키의 인증된 이메일 주소와 일치해야 합니다.

GitLab은 GPG 서명을 확인하기 위해 자체 키링을 사용합니다. 공개 키 서버에는 접근하지 않습니다.

GPG에 대한 자세한 내용은 관련 주제 목록을 참조하세요.

사용자의 공개 GPG 키 보기#

사용자의 공개 GPG 키를 보려면 다음 중 하나를 수행하세요:

https://gitlab.example.com/.gpg로 이동합니다. 사용자가 GPG 키를 구성한 경우 GitLab에서 해당 키가 표시되고, GPG 키가 구성되지 않은 사용자는 빈 페이지가 표시됩니다.
사용자의 프로필(예: https://gitlab.example.com/)로 이동합니다. 사용자 프로필의 오른쪽 상단 모서리에서 View public GPG keys( key )를 선택합니다. 이 버튼은 사용자가 키를 구성한 경우에만 표시됩니다.

커밋 서명 구성#

커밋에 서명하려면 로컬 머신과 GitLab 계정 모두를 구성해야 합니다:

GPG 키 생성#

아직 GPG 키가 없다면 새로 생성하세요:

운영 체제에 맞게 GPG를 설치합니다. 운영 체제에 gpg2가 설치되어 있다면 이 페이지의 명령어에서 gpg를 gpg2로 대체하세요.
사용 중인 gpg 버전에 맞는 명령어를 실행하여 키 쌍을 생성합니다:

# Use this command for the default version of GPG, including
# Gpg4win on Windows, and most macOS versions:
gpg --gen-key

# Use this command for versions of GPG later than 2.1.17:
gpg --full-gen-key

키가 사용할 알고리즘을 선택하거나 Enter를 눌러 기본 옵션인 RSA and RSA를 선택합니다.
키 길이를 비트 단위로 선택합니다. GitLab은 4096비트 키를 권장합니다.
키의 유효 기간을 지정합니다. 이 값은 주관적이며 기본값은 만료 없음입니다.
답변을 확인하려면 y를 입력합니다.
이름을 입력합니다.
이메일 주소를 입력합니다. GitLab 계정의 인증된 이메일 주소와 일치해야 합니다.
선택 사항. 이름 뒤에 괄호로 표시될 설명을 입력합니다.
GPG가 지금까지 입력한 정보를 표시합니다. 정보를 수정하거나 O(Okay)를 눌러 계속 진행합니다.
강력한 비밀번호를 입력한 다음 확인을 위해 다시 입력합니다.
다음 명령어를 실행하여 개인 GPG 키를 나열합니다. 을 키 생성 시 사용한 이메일 주소로 대체하세요:

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

출력에서 sec 행을 찾아 GPG 키 ID를 복사합니다. / 문자 이후부터 시작합니다. 이 예에서 키 ID는 30F2B65B9246B6CA입니다:

sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
      D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid                   [ultimate] Mr. Robot <your_email>
ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

연결된 공개 키를 표시하려면 다음 명령어를 실행합니다. 를 이전 단계의 GPG 키 ID로 대체하세요:

gpg --armor --export

BEGIN PGP PUBLIC KEY BLOCK과 END PGP PUBLIC KEY BLOCK 행을 포함하여 공개 키를 복사합니다. 이 키는 다음 단계에서 필요합니다.

계정에 GPG 키 추가#

사용자 설정에 GPG 키를 추가하려면:

GitLab에 로그인합니다.
오른쪽 상단 모서리에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
Add new key를 선택합니다.
Key에 공개 키를 붙여 넣습니다.
키를 계정에 추가하려면 Add key를 선택합니다.

GitLab에서 키의 지문, 이메일 주소, 생성 날짜가 표시됩니다.

키를 추가한 후에는 수정할 수 없습니다. 대신 문제가 있는 키를 제거하고 다시 추가하세요.

Git에 GPG 키 연결#

GPG 키를 생성하고 계정에 추가한 후에는 Git이 이 키를 사용하도록 구성해야 합니다:

다음 명령어를 실행하여 방금 생성한 개인 GPG 키를 나열합니다. 을 키의 이메일 주소로 대체하세요:

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

sec로 시작하는 GPG 개인 키 ID를 복사합니다. 이 예에서 개인 키 ID는 30F2B65B9246B6CA입니다:

sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
      D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid                   [ultimate] Mr. Robot <your_email>
ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

다음 명령어를 실행하여 키로 커밋에 서명하도록 Git을 구성합니다. 를 GPG 키 ID로 대체하세요:

git config --global user.signingkey

Git 커밋 서명#

계정에 공개 키를 추가한 후 개별 커밋에 수동으로 서명하거나 기본적으로 서명된 커밋을 사용하도록 Git을 구성할 수 있습니다:

개별 Git 커밋에 수동으로 서명:

서명하려는 커밋에 -S 플래그를 추가합니다:

git commit -S -m "My commit message"

GPG 키의 패스프레이즈를 묻는 메시지가 나타나면 입력합니다.
GitLab에 푸시하고 커밋이 검증되었는지 확인합니다.
다음 명령어를 실행하여 기본적으로 모든 Git 커밋에 서명합니다:

git config --global commit.gpgsign true

조건부로 서명 키 설정#

업무용과 개인용 등 서로 다른 목적을 위해 서명 키를 관리하는 경우, .gitconfig 파일에서 IncludeIf 구문을 사용하여 커밋에 서명할 키를 설정하세요.

필수 조건:

Git 버전 2.13 이상이 필요합니다.
기본 ~/.gitconfig 파일과 같은 디렉터리에 .gitconfig-gitlab과 같은 두 번째 파일을 만듭니다.
기본 ~/.gitconfig 파일에 GitLab이 아닌 프로젝트에서 작업하기 위한 Git 설정을 추가합니다.
기본 ~/.gitconfig 파일의 끝에 다음 정보를 추가합니다:

# The contents of this file are included only for GitLab.com URLs
[includeIf "hasconfig:remote.*.url:https://gitlab.com/**"]

# Edit this line to point to your alternative configuration file
path = ~/.gitconfig-gitlab

대체 .gitconfig-gitlab 파일에 GitLab 리포지터리에 커밋할 때 사용할 구성 재정의를 추가합니다. 명시적으로 재정의하지 않는 한 기본 ~/.gitconfig 파일의 모든 설정이 유지됩니다. 이 예에서:

# Alternative ~/.gitconfig-gitlab file
# These values are used for repositories matching the string 'gitlab.com',
# and override their corresponding values in ~/.gitconfig

[user]
email = you@example.com
signingkey = 

[commit]
gpgsign = true

태그 서명 및 검증#

히스토리

GitLab 18.3에서 render_gpg_signed_tags_verification_status라는 플래그와 함께 도입됨. 기본적으로 비활성화됨.

GitLab 19.0에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화됨.
GitLab 19.1에서 일반적으로 사용 가능해짐. 기능 플래그 render_gpg_signed_tags_verification_status 제거됨.

Git에 GPG 키를 연결한 후 태그에 서명할 수 있습니다:

Git 태그를 만들 때 -s 플래그를 추가합니다:

git tag -s v1.1.1 -m "My signed tag"

GitLab에 태그를 푸시합니다.
로컬에서 서명을 확인하려면 다음을 실행합니다:

git tag --verify v1.1.1

선택 사항. 모든 태그에 자동으로 서명하려면 다음을 실행합니다:

git config --global tag.gpgsign true

GPG 키 취소#

GPG 키가 손상된 경우 취소합니다. 키를 취소하면 과거 및 미래 커밋 모두에 영향을 미칩니다:

이 키로 서명된 과거 커밋은 검증되지 않음으로 표시됩니다.
이 키로 서명된 미래 커밋은 검증되지 않음으로 표시됩니다.

GPG 키를 취소하려면:

오른쪽 상단 모서리에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
삭제하려는 GPG 키 옆의 Revoke를 선택합니다.

GPG 키 제거#

GitLab 계정에서 GPG 키를 제거하면:

이 키로 서명된 이전 커밋은 검증된 상태로 유지됩니다.
이 키를 사용하려는 미래 커밋(생성되었지만 아직 푸시되지 않은 커밋 포함)은 검증되지 않음으로 표시됩니다.

계정에서 GPG 키를 제거하려면:

오른쪽 상단 모서리에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
삭제하려는 GPG 키 옆의 Remove( remove )를 선택합니다.

미래 및 과거 커밋 모두의 검증을 취소해야 한다면 대신 연결된 GPG 키를 취소하세요.

트러블슈팅#

시크릿 키를 사용할 수 없음#

secret key not available 또는 gpg: signing failed: secret key not available 오류가 발생하면 gpg 대신 gpg2를 사용해 보세요:

git config --global gpg.program gpg2

GPG 키에 비밀번호가 설정되어 있는데 비밀번호 입력 프롬프트가 나타나지 않으면 셸의 rc 파일(일반적으로 ~/.bashrc 또는 ~/.zshrc)에 export GPG_TTY=$(tty)를 추가하세요.

GPG가 데이터 서명에 실패함#

GPG 키에 비밀번호가 설정되어 있고 다음 오류 중 하나가 발생하는 경우:

error: gpg failed to sign the data
fatal: failed to write commit object
gpg: signing failed: Inappropriate ioctl for device

비밀번호 입력 프롬프트가 나타나지 않는 경우:

텍스트 편집기에서 셸의 구성 파일(일반적으로 ~/.bashrc 또는 ~/.zshrc)을 엽니다.
파일에 다음 행을 추가합니다:

export GPG_TTY=$(tty)

파일을 저장하고 텍스트 편집기를 종료합니다.
변경 사항을 적용합니다. 다음 중 하나를 선택하세요:

터미널을 재시작합니다.

source ~/.bashrc 또는 source ~/.zshrc를 실행합니다.

운영 체제 및 셸 구성에 따라 정확한 단계가 다를 수 있습니다.

GPG로 커밋 및 태그 서명

GitLab v19.2

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-06-19

요약

GPG(GNU Privacy Guard) 키로 GitLab 저장소에서 만드는 커밋에 서명할 수 있습니다.

GitLab은 OpenPGP, PGP, GPG 관련 모든 자료 및 구현에 대해 GPG라는 용어를 사용합니다.

GitLab이 커밋을 검증됨으로 간주하려면:

커밋 작성자에게 GPG 공개/개인 키 쌍이 있어야 합니다.
커밋 작성자의 공개 키가 GitLab 계정에 업로드되어 있어야 합니다.
GPG 공개 키에 있는 이메일 주소 중 하나가 커밋 작성자가 GitLab에서 사용하는 인증된 이메일 주소와 일치해야 합니다. 이 주소를 비공개로 유지하려면 GitLab이 프로필에서 제공하는 자동 생성된 비공개 커밋 이메일 주소를 사용하세요.
커밋 작성자의 이메일 주소가 GPG 키의 인증된 이메일 주소와 일치해야 합니다.

GitLab은 GPG 서명을 확인하기 위해 자체 키링을 사용합니다. 공개 키 서버에는 접근하지 않습니다.

GPG에 대한 자세한 내용은 관련 주제 목록을 참조하세요.

사용자의 공개 GPG 키 보기#

사용자의 공개 GPG 키를 보려면 다음 중 하나를 수행하세요:

https://gitlab.example.com/.gpg로 이동합니다. 사용자가 GPG 키를 구성한 경우 GitLab에서 해당 키가 표시되고, GPG 키가 구성되지 않은 사용자는 빈 페이지가 표시됩니다.
사용자의 프로필(예: https://gitlab.example.com/)로 이동합니다. 사용자 프로필의 오른쪽 상단 모서리에서 View public GPG keys( key )를 선택합니다. 이 버튼은 사용자가 키를 구성한 경우에만 표시됩니다.

커밋 서명 구성#

커밋에 서명하려면 로컬 머신과 GitLab 계정 모두를 구성해야 합니다:

GPG 키 생성#

아직 GPG 키가 없다면 새로 생성하세요:

운영 체제에 맞게 GPG를 설치합니다. 운영 체제에 gpg2가 설치되어 있다면 이 페이지의 명령어에서 gpg를 gpg2로 대체하세요.
사용 중인 gpg 버전에 맞는 명령어를 실행하여 키 쌍을 생성합니다:

# Use this command for the default version of GPG, including
# Gpg4win on Windows, and most macOS versions:
gpg --gen-key

# Use this command for versions of GPG later than 2.1.17:
gpg --full-gen-key

키가 사용할 알고리즘을 선택하거나 Enter를 눌러 기본 옵션인 RSA and RSA를 선택합니다.
키 길이를 비트 단위로 선택합니다. GitLab은 4096비트 키를 권장합니다.
키의 유효 기간을 지정합니다. 이 값은 주관적이며 기본값은 만료 없음입니다.
답변을 확인하려면 y를 입력합니다.
이름을 입력합니다.
이메일 주소를 입력합니다. GitLab 계정의 인증된 이메일 주소와 일치해야 합니다.
선택 사항. 이름 뒤에 괄호로 표시될 설명을 입력합니다.
GPG가 지금까지 입력한 정보를 표시합니다. 정보를 수정하거나 O(Okay)를 눌러 계속 진행합니다.
강력한 비밀번호를 입력한 다음 확인을 위해 다시 입력합니다.
다음 명령어를 실행하여 개인 GPG 키를 나열합니다. 을 키 생성 시 사용한 이메일 주소로 대체하세요:

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

출력에서 sec 행을 찾아 GPG 키 ID를 복사합니다. / 문자 이후부터 시작합니다. 이 예에서 키 ID는 30F2B65B9246B6CA입니다:

sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
      D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid                   [ultimate] Mr. Robot <your_email>
ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

연결된 공개 키를 표시하려면 다음 명령어를 실행합니다. 를 이전 단계의 GPG 키 ID로 대체하세요:

gpg --armor --export

BEGIN PGP PUBLIC KEY BLOCK과 END PGP PUBLIC KEY BLOCK 행을 포함하여 공개 키를 복사합니다. 이 키는 다음 단계에서 필요합니다.

계정에 GPG 키 추가#

사용자 설정에 GPG 키를 추가하려면:

GitLab에 로그인합니다.
오른쪽 상단 모서리에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
Add new key를 선택합니다.
Key에 공개 키를 붙여 넣습니다.
키를 계정에 추가하려면 Add key를 선택합니다.

GitLab에서 키의 지문, 이메일 주소, 생성 날짜가 표시됩니다.

키를 추가한 후에는 수정할 수 없습니다. 대신 문제가 있는 키를 제거하고 다시 추가하세요.

Git에 GPG 키 연결#

GPG 키를 생성하고 계정에 추가한 후에는 Git이 이 키를 사용하도록 구성해야 합니다:

다음 명령어를 실행하여 방금 생성한 개인 GPG 키를 나열합니다. 을 키의 이메일 주소로 대체하세요:

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

sec로 시작하는 GPG 개인 키 ID를 복사합니다. 이 예에서 개인 키 ID는 30F2B65B9246B6CA입니다:

sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
      D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
uid                   [ultimate] Mr. Robot <your_email>
ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]

다음 명령어를 실행하여 키로 커밋에 서명하도록 Git을 구성합니다. 를 GPG 키 ID로 대체하세요:

git config --global user.signingkey

Git 커밋 서명#

계정에 공개 키를 추가한 후 개별 커밋에 수동으로 서명하거나 기본적으로 서명된 커밋을 사용하도록 Git을 구성할 수 있습니다:

개별 Git 커밋에 수동으로 서명:

서명하려는 커밋에 -S 플래그를 추가합니다:

git commit -S -m "My commit message"

GPG 키의 패스프레이즈를 묻는 메시지가 나타나면 입력합니다.
GitLab에 푸시하고 커밋이 검증되었는지 확인합니다.
다음 명령어를 실행하여 기본적으로 모든 Git 커밋에 서명합니다:

git config --global commit.gpgsign true

조건부로 서명 키 설정#

업무용과 개인용 등 서로 다른 목적을 위해 서명 키를 관리하는 경우, .gitconfig 파일에서 IncludeIf 구문을 사용하여 커밋에 서명할 키를 설정하세요.

필수 조건:

Git 버전 2.13 이상이 필요합니다.
기본 ~/.gitconfig 파일과 같은 디렉터리에 .gitconfig-gitlab과 같은 두 번째 파일을 만듭니다.
기본 ~/.gitconfig 파일에 GitLab이 아닌 프로젝트에서 작업하기 위한 Git 설정을 추가합니다.
기본 ~/.gitconfig 파일의 끝에 다음 정보를 추가합니다:

# The contents of this file are included only for GitLab.com URLs
[includeIf "hasconfig:remote.*.url:https://gitlab.com/**"]

# Edit this line to point to your alternative configuration file
path = ~/.gitconfig-gitlab

대체 .gitconfig-gitlab 파일에 GitLab 리포지터리에 커밋할 때 사용할 구성 재정의를 추가합니다. 명시적으로 재정의하지 않는 한 기본 ~/.gitconfig 파일의 모든 설정이 유지됩니다. 이 예에서:

# Alternative ~/.gitconfig-gitlab file
# These values are used for repositories matching the string 'gitlab.com',
# and override their corresponding values in ~/.gitconfig

[user]
email = you@example.com
signingkey = 

[commit]
gpgsign = true

태그 서명 및 검증#

히스토리

GitLab 18.3에서 render_gpg_signed_tags_verification_status라는 플래그와 함께 도입됨. 기본적으로 비활성화됨.

GitLab 19.0에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화됨.
GitLab 19.1에서 일반적으로 사용 가능해짐. 기능 플래그 render_gpg_signed_tags_verification_status 제거됨.

Git에 GPG 키를 연결한 후 태그에 서명할 수 있습니다:

Git 태그를 만들 때 -s 플래그를 추가합니다:

git tag -s v1.1.1 -m "My signed tag"

GitLab에 태그를 푸시합니다.
로컬에서 서명을 확인하려면 다음을 실행합니다:

git tag --verify v1.1.1

선택 사항. 모든 태그에 자동으로 서명하려면 다음을 실행합니다:

git config --global tag.gpgsign true

GPG 키 취소#

GPG 키가 손상된 경우 취소합니다. 키를 취소하면 과거 및 미래 커밋 모두에 영향을 미칩니다:

이 키로 서명된 과거 커밋은 검증되지 않음으로 표시됩니다.
이 키로 서명된 미래 커밋은 검증되지 않음으로 표시됩니다.

GPG 키를 취소하려면:

오른쪽 상단 모서리에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
삭제하려는 GPG 키 옆의 Revoke를 선택합니다.

GPG 키 제거#

GitLab 계정에서 GPG 키를 제거하면:

이 키로 서명된 이전 커밋은 검증된 상태로 유지됩니다.
이 키를 사용하려는 미래 커밋(생성되었지만 아직 푸시되지 않은 커밋 포함)은 검증되지 않음으로 표시됩니다.

계정에서 GPG 키를 제거하려면:

오른쪽 상단 모서리에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
삭제하려는 GPG 키 옆의 Remove( remove )를 선택합니다.

미래 및 과거 커밋 모두의 검증을 취소해야 한다면 대신 연결된 GPG 키를 취소하세요.

트러블슈팅#

시크릿 키를 사용할 수 없음#

secret key not available 또는 gpg: signing failed: secret key not available 오류가 발생하면 gpg 대신 gpg2를 사용해 보세요:

git config --global gpg.program gpg2

GPG가 데이터 서명에 실패함#

GPG 키에 비밀번호가 설정되어 있고 다음 오류 중 하나가 발생하는 경우:

error: gpg failed to sign the data
fatal: failed to write commit object
gpg: signing failed: Inappropriate ioctl for device

비밀번호 입력 프롬프트가 나타나지 않는 경우:

텍스트 편집기에서 셸의 구성 파일(일반적으로 ~/.bashrc 또는 ~/.zshrc)을 엽니다.
파일에 다음 행을 추가합니다:

export GPG_TTY=$(tty)

파일을 저장하고 텍스트 편집기를 종료합니다.
변경 사항을 적용합니다. 다음 중 하나를 선택하세요:

터미널을 재시작합니다.

source ~/.bashrc 또는 source ~/.zshrc를 실행합니다.

운영 체제 및 셸 구성에 따라 정확한 단계가 다를 수 있습니다.

GPG로 커밋 및 태그 서명

사용자의 공개 GPG 키 보기#

커밋 서명 구성#

GPG 키 생성#

계정에 GPG 키 추가#

Git에 GPG 키 연결#

Git 커밋 서명#

조건부로 서명 키 설정#

태그 서명 및 검증#

GPG 키 취소#

GPG 키 제거#

관련 주제#

트러블슈팅#

시크릿 키를 사용할 수 없음#

GPG가 데이터 서명에 실패함#

GPG로 커밋 및 태그 서명

사용자의 공개 GPG 키 보기#

커밋 서명 구성#

GPG 키 생성#

계정에 GPG 키 추가#

Git에 GPG 키 연결#

Git 커밋 서명#

조건부로 서명 키 설정#

태그 서명 및 검증#

GPG 키 취소#

GPG 키 제거#

관련 주제#

트러블슈팅#

시크릿 키를 사용할 수 없음#

GPG가 데이터 서명에 실패함#