GitLab 리포지터리에서 작성하는 커밋에 GPG(GNU Privacy Guard) 키로 서명할 수 있습니다.

GitLab 이 커밋을 검증된 것으로 인정하려면 다음 조건을 충족해야 합니다.

• 커미터에게 GPG 공개 키와 개인 키 쌍이 있어야 합니다.
• 커미터의 공개 키가 GitLab 계정에 업로드되어 있어야 합니다.
• GPG 공개 키에 포함된 이메일 주소 중 하나가 커미터가 GitLab에서 사용하는 검증된 이메일 주소와 일치해야 합니다. GitLab은 취소된 사용자 ID의 이메일 주소를 무시합니다. 이 주소를 비공개로 유지하려면 GitLab 이 프로필에서 자동으로 생성해 제공하는 비공개 커밋 이메일 주소를 사용합니다.
• 커미터의 이메일 주소가 GPG 키의 검증된 이메일 주소와 일치해야 합니다.

GitLab은 자체 키링을 사용해 GPG 서명을 검증합니다. 공개 키 서버에는 접속하지 않습니다.

GPG에 대한 자세한 내용은 관련 주제 목록을 참고합니다.

사용자의 공개 GPG 키 보기#

사용자의 공개 GPG 키는 다음 두 가지 방법으로 확인할 수 있습니다.

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

커밋 서명 구성#

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

1. GPG 키를 생성합니다.
2. 계정에 GPG 키를 추가합니다.
3. GPG 키를 Git에 연결합니다.
4. Git 커밋에 서명합니다.

GPG 키 생성#

GPG 키가 아직 없다면 다음 단계로 생성합니다.

1. 운영 체제에 맞는 GPG를 설치합니다. 운영 체제에 gpg2가 설치되어 있다면 이 페이지의 명령에서 gpg를 gpg2로 바꿔 실행합니다.

2. 키 쌍을 생성하려면 사용 중인 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
   

3. 키가 사용할 알고리즘을 선택하거나, Enter를 눌러 기본 옵션인 RSA and RSA를 선택합니다.

4. 키 길이를 비트 단위로 선택합니다. GitLab은 4096비트 키를 권장합니다.

5. 키의 유효 기간을 지정합니다. 이 값은 사용자가 판단할 사항이며 기본값은 만료 없음입니다.

6. 입력한 내용을 확인하려면 y를 입력합니다.

7. 이름을 입력합니다.

8. 이메일 주소를 입력합니다. GitLab 계정의 검증된 이메일 주소와 일치해야 합니다.

9. 선택 사항. 이름 뒤 괄호 안에 표시할 주석을 입력합니다.

10. GPG가 지금까지 입력한 정보를 표시합니다. 정보를 수정하거나 O(Okay)를 눌러 계속 진행합니다.

11. 강력한 비밀번호를 입력한 다음, 확인을 위해 한 번 더 입력합니다.

12. 개인 GPG 키를 조회하려면 다음 명령을 실행합니다. 이때 은 키를 생성할 때 사용한 이메일 주소로 바꿉니다.

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

13. 출력에서 sec 줄을 찾아 GPG 키 ID를 복사합니다. 키 ID는 / 문자 뒤에서 시작합니다. 다음 예시에서 키 ID는 30F2B65B9246B6CA 입니다.

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

14. 연결된 공개 키를 표시하려면 다음 명령을 실행합니다. 이때 는 이전 단계에서 확인한 GPG 키 ID로 바꿉니다.

    gpg --armor --export 
    

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

계정에 GPG 키 추가#

사용자 설정에 GPG 키를 추가하려면 다음 단계를 수행합니다.

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

GitLab 이 키의 지문, 이메일 주소, 생성 날짜를 표시합니다. GPG 키에서 사용자 ID를 취소하면 GitLab은 해당 이메일 주소를 표시하지 않습니다. 해당 주소를 커미터 이메일로 사용하는 커밋은 검증되지 않음으로 표시됩니다.

키를 추가한 뒤에는 편집할 수 없습니다. 대신 문제가 있는 키를 제거하고 다시 추가합니다.

Git에 GPG 키 연결#

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

1. 방금 생성한 개인 GPG 키를 조회하려면 다음 명령을 실행합니다. 이때 은 키에 사용한 이메일 주소로 바꿉니다.

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

2. 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]
   

3. 해당 키로 커밋에 서명하도록 Git을 구성하려면 다음 명령을 실행합니다. 이때 는 사용자의 GPG 키 ID로 바꿉니다.

   git config --global user.signingkey 
   

Git 커밋 서명#

계정에 공개 키를 추가한 다음에는, 개별 커밋에 직접 서명하거나 서명된 커밋을 기본값으로 사용하도록 Git을 구성할 수 있습니다.

• 개별 Git 커밋에 직접 서명합니다.

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

     git commit -S -m "My commit message"
     

  2. 요청이 표시되면 GPG 키의 패스프레이즈를 입력합니다.

  3. GitLab에 푸시한 다음 커밋이 검증되었는지 확인합니다.

• 다음 명령을 실행해 모든 Git 커밋에 기본으로 서명합니다.

  git config --global commit.gpgsign true
  

조건부로 서명 키 설정#

업무용과 개인용처럼 용도별로 서명 키를 따로 관리한다면, .gitconfig 파일에 IncludeIf 문을 사용해 커밋 서명에 사용할 키를 지정합니다.

사전 요구 사항:

• Git 2.13 이상 버전이 필요합니다.

1. 기본 ~/.gitconfig 파일과 같은 디렉터리에 .gitconfig-gitlab과 같은 두 번째 파일을 생성합니다.

2. 기본 ~/.gitconfig 파일에 GitLab 이 아닌 프로젝트의 작업에 사용할 Git 설정을 추가합니다.

3. 기본 ~/.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
   

4. 대체 파일인 .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
   

태그 서명 및 검증#

GPG 키를 Git에 연결한 다음에는 태그에 서명할 수 있습니다.

1. Git 태그를 생성할 때 -s 플래그를 추가합니다.

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

2. 태그를 GitLab에 푸시합니다.

3. 로컬에서 서명을 검증하려면 다음 명령을 실행합니다.

   git tag --verify v1.1.1
   

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

   git config --global tag.gpgsign true
   

GPG 키 취소#

GPG 키가 유출되었다면 해당 키를 취소합니다. 키를 취소하면 이후 커밋과 이전 커밋이 모두 영향을 받습니다.

• 이 키로 서명된 이전 커밋은 검증되지 않음으로 표시됩니다.
• 이 키로 서명된 이후 커밋도 검증되지 않음으로 표시됩니다.

GitLab에서 키를 취소하는 것은 GnuPG로 키의 사용자 ID 중 하나를 취소하는 것과 같지 않습니다. 사용자 ID를 취소하면 해당 사용자 ID의 이메일 주소를 커미터 이메일로 사용하는 커밋만 검증되지 않음으로 표시됩니다.

GPG 키를 취소하려면 다음 단계를 수행합니다.

1. 오른쪽 위에서 아바타를 선택합니다.
2. Edit profile을 선택합니다.
3. 왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
4. 취소하려는 GPG 키 옆에서 Revoke를 선택합니다.

GPG 키 제거#

GitLab 계정에서 GPG 키를 제거하면 다음과 같이 동작합니다.

• 이 키로 서명된 이전 커밋은 검증된 상태로 유지됩니다.
• 이 키를 사용하려는 이후 커밋(생성했지만 아직 푸시하지 않은 커밋 포함)은 검증되지 않습니다.

계정에서 GPG 키를 제거하려면 다음 단계를 수행합니다.

1. 오른쪽 위에서 아바타를 선택합니다.
2. Edit profile을 선택합니다.
3. 왼쪽 사이드바에서 Access > GPG keys를 선택합니다.
4. 삭제하려는 GPG 키 옆에서 Remove ([remove])를 선택합니다.

이후 커밋과 이전 커밋을 모두 검증되지 않음으로 만들어야 한다면, 대신 연결된 GPG 키를 취소합니다.

관련 주제#

• 웹 UI에서 작성한 커밋의 커밋 서명 구성
• GPG 자료:
  • Git Tools - Signing Your Work
  • Managing OpenPGP Keys
  • OpenPGP Best Practices
  • 서브키가 있는 새 GPG 키 생성 (고급)
  • 인스턴스의 GPG 키 보기
  • Beyond Identity 통합

문제 해결#

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

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

비밀번호 입력 프롬프트가 표시되지 않는다면 다음 단계를 수행합니다.

1. 주로 ~/.bashrc 또는 ~/.zshrc 인 셸 구성 파일을 텍스트 편집기로 엽니다.

2. 파일에 다음 줄을 추가합니다.

   export GPG_TTY=$(tty)
   

3. 파일을 저장하고 텍스트 편집기를 종료합니다.

4. 변경 사항을 적용합니다. 다음 중 하나를 선택합니다.

   • 터미널을 다시 시작합니다.
   • source ~/.bashrc 또는 source ~/.zshrc를 실행합니다.