GitLab을 통해 SSH 키를 사용하여 통신하기

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

Git은 분산 버전 관리 시스템으로, 로컬에서 작업한 다음 변경 사항을 서버에 공유하거나 push할 수 있습니다. 이 경우, push할 서버는 GitLab입니다.

GitLab은 SSH 프로토콜을 사용하여 Git과 안전하게 통신합니다. GitLab 원격 서버에 인증하기 위해 SSH 키를 사용하면 매번 사용자 이름과 암호를 제공할 필요가 없습니다.

SSH 키란

SSH는 공개 키와 개인 키 두 개의 키를 사용합니다.

  • 공개 키는 배포할 수 있습니다.
  • 개인 키는 보호해야 합니다.

공개 키를 업로드하여 비밀 데이터를 공개하는 일은 불가능합니다. SSH 공개 키를 복사하거나 업로드해야 할 때 실수로 개인 키를 복사하거나 업로드하지 않도록 주의하세요.

GitLab을 사용하여 커밋에 서명하는 경우 GitLab 및 데이터 사용이 더욱 안전해집니다. 이 서명은 공개 키를 사용하여 누구나 확인할 수 있습니다.

세부 정보는 비대칭 암호화(Public-key cryptography)를 참조하세요.

사전 조건

GitLab과 SSH를 사용하여 통신하려면 다음이 필요합니다.

  • GNU/Linux, macOS, Windows 10에 미리 설치된 OpenSSH 클라이언트.
  • SSH 버전 6.5 이상. 이전 버전은 안전하지 않은 MD5 서명을 사용했습니다.

시스템에 설치된 SSH 버전을 확인하려면 ssh -V를 실행하세요.

지원되는 SSH 키 유형

GitLab과 통신하기 위해 다음 SSH 키 유형을 사용할 수 있습니다.

관리자는 허용된 키 및 최소 길이를 제한할 수 있습니다.

ED25519 SSH 키

책 Practical Cryptography With Go에서는 ED25519 키가 RSA 키보다 보안 및 성능 측면에서 더 우수하다고 제안합니다.

OpenSSH 6.5에서 2014년에 ED25519 SSH 키가 소개되었으며 대부분의 운영 체제에서 사용할 수 있어야 합니다.

ED25519_SK SSH 키

GitLab에서 ED25519_SK SSH 키를 사용하려면 로컬 클라이언트와 GitLab 서버에 OpenSSH 8.2 이상이 설치되어 있어야 합니다.

ECDSA_SK SSH 키

GitLab에서 ECDSA_SK SSH 키를 사용하려면 로컬 클라이언트와 GitLab 서버에 OpenSSH 8.2 이상이 설치되어 있어야 합니다.

RSA SSH 키

  • GitLab 16.3에서 최대 RSA 키 길이 변경.

사용 가능한 문서에 따르면 ED25519이 RSA보다 보안이 더 우수하다고 합니다.

RSA 키를 사용하는 경우 미국 국립표준기술연구소(NIST)는 공개 800-57 파트 3 (PDF)에서 최소 2048비트의 키 크기를 권장합니다. Go의 한계로 인해 RSA 키는 8192비트를 초과할 수 없습니다.

기본 키 크기는 사용 중인 ssh-keygen 버전에 따라 다릅니다. 자세한 내용은 설치된 ssh-keygen 명령어의 man 페이지를 참조하세요.

기존 SSH 키 쌍이 있는지 확인

새 키 쌍을 생성하기 전에 기존 키 쌍이 있는지 확인하세요.

  1. 홈 디렉터리로 이동합니다.
  2. .ssh/ 하위 디렉터리로 이동합니다. .ssh/ 하위 디렉터리가 없는 경우 홈 디렉터리에 있지 않거나 이전에 ssh를 사용하지 않았습니다. 후자의 경우 SSH 키 쌍 생성이 필요합니다.

  3. 다음 항목 중 하나이름 규칙을 따르는 파일이 있는지 확인합니다.

    알고리즘 공개 키 개인 키
    ED25519 (권장) id_ed25519.pub id_ed25519
    ED25519_SK id_ed25519_sk.pub id_ed25519_sk
    ECDSA_SK id_ecdsa_sk.pub id_ecdsa_sk
    RSA (최소 2048비트 키 크기) id_rsa.pub id_rsa
    DSA (지원 중단) id_dsa.pub id_dsa
    ECDSA id_ecdsa.pub id_ecdsa

SSH 키 쌍 생성

기존 SSH 키 쌍이 없는 경우 새로 생성하세요.

  1. 터미널을 엽니다.

  2. ssh-keygen -t 다음에 키 유형과 선택적인 주석을 실행합니다. 이 주석은 생성된 .pub 파일에 포함됩니다. 주석으로 이메일 주소를 사용하는 것이 좋습니다.

    예를 들어, ED25519의 경우: 

    ssh-keygen -t ed25519 -C "<주석>"

    2048비트 RSA의 경우: 

    ssh-keygen -t rsa -b 2048 -C "<주석>"

  3. Enter 키를 누릅니다. 다음과 유사한 출력이 표시됩니다. 

    Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

  4. 제안된 파일 이름과 디렉터리를 수락합니다. 배포 키를 생성하거나 기타 키를 저장하는 특정 디렉터리에 저장하려는 경우에만 다른 디렉터리에 저장하세요.

    또한 SSH 키 쌍을 특정 호스트에 지정할 수도 있습니다.

  5. 암호구문을 지정하세요: 

    Enter passphrase (empty for no passphrase):
Enter same passphrase again:

    파일이 저장된 위치에 대한 정보를 포함한 확인이 표시됩니다.

공개 및 개인 키가 생성됩니다. 공개 SSH 키를 GitLab 계정에 추가하고 개인 키를 안전하게 보관하세요.

SSH를 다른 디렉터리로 지정하는 방법 구성하기

만약 SSH 키페어를 기본 디렉터리에 저장하지 않았다면 SSH 클라이언트를 이용하여 개인 키가 저장된 디렉터리를 지정하세요.

  1. 터미널을 열고 다음 명령을 실행하세요: 

    eval $(ssh-agent -s)
ssh-add <개인 SSH 키가 있는 디렉터리>

  2. 이러한 설정을 ~/.ssh/config 파일에 저장하세요. 예를 들어: 

    # GitLab.com
Host gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa
   
# 프라이빗 GitLab 인스턴스
Host gitlab.company.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/example_com_rsa

이러한 설정에 대한 자세한 내용은 SSH 구성 메뉴얼의 man ssh_config 페이지를 참조하세요.

공개 SSH 키는 GitLab에 고유해야 하며, 이는 사용자 계정에 바인딩됩니다. SSH로 코드를 푸시할 때 SSH 키가 유일한 식별자여야 합니다. 이것은 반드시 하나의 사용자에게 매핑되어야 합니다.

SSH 키 암호 업데이트하기

SSH 키의 암호를 업데이트할 수 있습니다:

  1. 터미널을 열고 다음 몤령을 실행하세요: 

    ssh-keygen -p -f /path/to/ssh_key

  2. 프롬프트에 암호를 입력한 후 Enter 키를 누릅니다.

RSA 키페어를 보안이 더 강력한 형식으로 업그레이드하기

만약 OpenSSH 버전이 6.5에서 7.8 사이라면, 터미널을 열고 다음 명령을 실행하여 개인 RSA SSH 키를 보다 안전한 OpenSSH 형식으로 저장할 수 있습니다. 

ssh-keygen -o -f ~/.ssh/id_rsa

또는 보다 안전한 암호화 형식의 새로운 RSA 키를 생성할 수 있습니다. 이를 위해 다음 명령을 사용하세요. 

ssh-keygen -o -t rsa -b 4096 -C "<코멘트>"

FIDO2 하드웨어 보안 키를 위한 SSH 키페어 생성하기

ED25519_SK 또는 ECDSA_SK SSH 키를 생성하려면 OpenSSH 8.2 이상을 사용해야 합니다:

  1. 컴퓨터에 하드웨어 보안 키를 삽입하세요.
  2. 터미널을 열어주세요.

  3. ssh-keygen -t 다음에 키 유형과 선택 사항 코멘트를 입력한 후 실행하세요. 이 코멘트는 생성된 .pub 파일에 포함됩니다. 코멘트에는 이메일 주소를 사용하는 것이 좋습니다.

    예를 들어, ED25519_SK의 경우: 

    ssh-keygen -t ed25519-sk -C "<코멘트>"

    ECDSA_SK의 경우: 

    ssh-keygen -t ecdsa-sk -C "<코멘트>"

    보안 키가 FIDO2 레지던트 키를 지원하는 경우, SSH 키 생성 시 이를 활성화할 수 있습니다: 

    ssh-keygen -t ed25519-sk -O resident -C "<코멘트>"

    -O resident는 키가 FIDO 인증자 자체에 저장되어야 함을 나타냅니다. 레지던트 키는 새로운 컴퓨터로 가져오기가 쉽기 때문에, 생성된 보안 키로부터 직접적으로 ssh-add -K나 ssh-keygen -K로 불러올 수 있습니다.

  4. Enter 키를 누릅니다. 다음과 같은 출력이 표시됩니다: 

    공개/개인 ed25519-sk 키페어 생성 중.
귀하의 인증기를 터치해 키 생성을 승인할 수 있습니다.

  5. 하드웨어 보안 키의 버튼을 누릅니다.

  6. 제안된 파일명과 디렉터리를 수락하세요: 

    키파일을 저장할 경로 입력 (예: /home/user/.ssh/id_ed25519_sk):

  7. 암호를 지정하세요: 

    암호 입력 (암호를 사용하지 않으려면 공백으로 두세요):
같은 암호를 다시 입력하세요:

    파일이 저장된 위치에 대한 정보를 포함한 확인이 표시됩니다.

공개 및 개인 키가 생성됩니다. 공개 SSH 키를 GitLab 계정에 추가하세요.

패스워드 관리자를 사용하여 SSH 키페어 생성하기

1Password로 SSH 키페어 생성하기

1Password 및 1Password 브라우저 확장 프로그램을 사용하여 다음 중 하나를 수행할 수 있습니다:

  • 새로운 SSH 키를 자동으로 생성합니다.
  • 1Password 보관함의 기존 SSH 키를 사용하여 GitLab에 인증합니다.
  1. GitLab에 로그인합니다.
  2. 왼쪽 사이드바에서 아바타를 선택합니다.
  3. 프로필 편집을 선택합니다.
  4. 왼쪽 사이드바에서 SSH 키를 선택합니다.
  5. 새 키 추가를 선택합니다.
  6. 키를 선택하면 1Password 도우미가 나타납니다.
  7. 1Password 아이콘을 선택하고 1Password를 잠금 해제합니다.
  8. 그럼 SSH 키 생성 또는 기존 SSH 키를 선택하여 공개 키를 채우기 위해 출현합니다.
  9. 제목 상자에 직장 노트북이나 집 워크스테이션과 같은 설명을 입력하세요.
  10. 선택 사항: 키의 사용 유형을 업데이터할 수 있습니다. 인증 또는 서명 또는 둘 다를 위해서 사용할 수 있습니다. 인증 및 서명이 기본값입니다.
  11. 선택 사항: 기본 만료일을 수정하려면 만료일 업데이트하세요.
  12. 키 추가를 선택합니다.

SSH 키 사용에 대한 자세한 내용은 1Password 문서를 참조하세요.

GitLab 계정에 SSH 키 추가하기

  • GitLab 15.4에서 소개된 키의 제안 기본 만료일.
  • GitLab 15.7에서 추가된 SSH 키 사용 유형.

GitLab에서 SSH를 사용하려면 공개 키를 GitLab 계정에 복사하세요:

  1. 공개 키 파일의 내용을 복사하세요. 이를 매뉴얼으로 수행하거나 스크립트를 사용할 수 있습니다. 예를 들어, ED25519 키를 클립보드에 복사하기 위해:

    macOS 

    tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

    리눅스 (xclip 패키지가 필요함) 

    xclip -sel clip < ~/.ssh/id_ed25519.pub

    윈도우 Git Bash 

    cat ~/.ssh/id_ed25519.pub | clip

    파일명을 대체하세요. RSA인 경우 id_rsa.pub를 사용하세요.

  2. GitLab에 로그인합니다.
  3. 왼쪽 사이드바에서 아바타를 선택합니다.
  4. 프로필 편집을 선택합니다.
  5. 왼쪽 사이드바에서 SSH 키를 선택합니다.
  6. 새 키 추가를 선택합니다.
  7. 키 상자에 공개 키의 내용을 붙여넣습니다. 매뉴얼으로 키를 복사한 경우, ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, sk-ecdsa-sha2-nistp256@openssh.com, 또는 sk-ssh-ed25519@openssh.com로 시작하는 전체 키를 복사했는지 확인하세요. 그리고 주석으로 끝날 수 있습니다.
  8. 제목 상자에 직장 노트북 또는 집 워크스테이션과 같은 설명을 입력하세요.
  9. 선택 사항: 키의 사용 유형을 업데이터할 수 있습니다. 인증 또는 서명 또는 둘 다를 위해서 사용할 수 있습니다. 인증 및 서명이 기본값입니다.
  10. 선택 사항: 기본 만료일을 수정하려면 만료일을 업데이트하세요.
    • GitLab 13.12 이전의 경우, 만료일은 정보만 포함합니다. 키의 사용을 방지하지는 않습니다. 관리자는 만료일을 확인하고 키 삭제할 때 이를 가이드로 사용할 수 있습니다.
    • GitLab은 매일 UTC 02:00에 모든 SSH 키를 확인합니다. 현재 날짜에 만료되는 모든 SSH 키에 대해 만료 알림 이메일을 보냅니다. (GitLab 13.11에서 소개.)
    • GitLab은 매일 UTC 01:00에 만료 예정인 일주일 이후에 만료 알림 이메일을 보냅니다. (GitLab 13.11에서 소개.)
  11. 키 추가를 선택합니다.

연결 확인

SSH 키가 올바르게 추가되었는지 확인합니다.

다음 명령어는 예시 호스트 이름 ‘gitlab.example.com’을 사용합니다. 이 예시 호스트 이름을 GitLab 인스턴스의 호스트 이름으로 대체하세요. 예를 들어 git@gitlab.com입니다. 기본적으로 GitLab은 git 사용자 이름을 사용하여 인증합니다. 이는 관리자에 의해 변경된 경우에도 달라질 수 있습니다.

  1. 올바른 서버에 연결하는지 확인하려면 서버의 SSH 호스트 키 지문을 확인하세요.
    • GitLab.com의 경우 SSH 호스트 키 지문 설명서를 참조하세요.
    • GitLab.com 또는 다른 GitLab 인스턴스의 경우, gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints를 참조하세요. 여기서 gitlab.example.com은 gitlab.com (GitLab.com의 경우) 또는 GitLab 인스턴스의 주소입니다.

  2. 터미널을 열고 다음 명령을 실행하여 gitlab.example.com을 사용하는 GitLab 인스턴스 URL로 대체하세요: 

    ssh -T git@gitlab.example.com

  3. 처음 연결하는 경우 GitLab 호스트의 신뢰성을 확인해야 합니다. 다음과 유사한 메시지가 표시되면: 

    The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hosts.

    ‘yes’를 입력하고 Enter를 누릅니다.

  4. ssh -T git@gitlab.example.com 명령을 다시 실행합니다. Welcome to GitLab, @username! 메시지를 받아야 합니다.

환영 메시지가 표시되지 않으면 ssh를 상세 모드로 실행하여 문제를 해결할 수 있습니다: 

ssh -Tvvv git@gitlab.example.com

다른 리포지터리에 대해 다른 키 사용

각 리포지터리에 다른 키를 사용할 수 있습니다.

터미널을 열고 다음 명령을 실행합니다: 

git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"

이 명령은 SSH 에이전트를 사용하지 않으며 Git 2.10 이상이 필요합니다. ssh 명령 옵션에 대한 자세한 정보는 ssh 및 ssh_config의 매뉴얼 페이지를 참조하세요.

계정의 SSH 키 보기

계정의 SSH 키를 확인하려면:

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 왼쪽 사이드바에서 SSH 키를 선택합니다.

기존 SSH 키는 페이지 하단에 나열됩니다. 정보에는 다음이 포함됩니다:

  • 키 이름.
  • 공개 지문.
  • 만료일.
  • 허용된 사용 유형.
  • 키를 마지막으로 사용한 시간.

SSH 키 삭제

SSH 키를 영구적으로 삭제하려면:

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 왼쪽 사이드바에서 SSH 키를 선택합니다.
  4. 삭제하려는 키 옆에서 제거()를 선택합니다.
  5. 삭제를 선택합니다.

단일 GitLab 인스턴스에서 여러 계정 사용

한 인스턴스의 GitLab에 여러 계정을 사용할 수 있습니다. 이를 위해 이전 주제의 명령을 사용할 수 있습니다. 그러나 IdentitiesOnly를 yes로 설정하더라도 IdentityFile이 Host 블록 외부에 존재하는 경우 로그인할 수 없습니다.

대신 ~/.ssh/config 파일에서 호스트에 별칭을 할당할 수 있습니다.

  • Host에는 user_1.gitlab.com 및 user_2.gitlab.com과 같은 별칭을 사용합니다. 고급 구성은 유지 보수가 더 어려우며, 이러한 문자열은 git remote와 같은 도구를 사용할 때 이해하기 쉽습니다.
  • IdentityFile에는 개인 키의 경로를 사용합니다. 
# 사용자1 계정 신원
Host <user_1.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key1>

# 사용자2 계정 신원
Host <user_2.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key2>

이제 user_1을 위한 리포지터리를 복제하려면 git clone 명령에서 user_1.gitlab.com을 사용합니다. 

git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git

이전에 별칭을 origin으로 지정한 이전에 복제한 리포지터리를 업데이트하려면: 

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
note
개인 및 공개 키에는 민감한 데이터가 포함되어 있습니다. 파일 권한이 다른 사용자에게는 액세스할 수 없지만 본인에게는 읽을 수 있게 해야 합니다.

이중 요소 인증 (2FA) 구성

SSH를 통한 Git의 이중 요소 인증 (2FA)을 설정할 수 있습니다. ED25519_SK 또는 ECDSA_SK SSH 키를 사용하는 것이 좋습니다.

Eclipse에서 EGit 사용

EGit을 사용 중이라면 Eclipse에 SSH 키 추가할 수 있습니다.

Microsoft Windows에서 SSH 사용

Windows 10을 사용 중이라면 Windows Subsystem for Linux (WSL)을 사용하여 이미 git과 ssh가 사전 설치된 WSL 2를 사용하거나 SSH를 PowerShell을 통해 사용하도록 Git for Windows를 설치할 수 있습니다.

WSL에서 생성된 SSH 키는 Git for Windows에서 직접 사용할 수 없으며 그 반대도 마찬가지로 적용됩니다. 두 환경 간에 서로 다른 홈 디렉터리를 가지고 있기 때문입니다:

  • WSL: /home/<user>
  • Git for Windows: C:\Users\<user>

동일한 키를 사용하려면 .ssh/ 디렉터리를 복사하거나 각 환경에서 키를 생성할 수 있습니다.

Windows 11을 실행 중이고 OpenSSH for Windows를 사용 중이라면 HOME 환경 변수가 올바르게 설정되어 있는지 확인하세요. 그렇지 않은 경우 개인 SSH 키를 찾을 수 없을 수 있습니다.

대체 도구로는 다음이 포함됩니다:

GitLab 서버에서 SSH 설정 재정의하기

GitLab은 시스템에 설치된 SSH 데몬과 통합되어 모든 액세스 요청을 처리하는 사용자(일반적으로 git이라고 명명됨)를 지정합니다. SSH를 통해 GitLab 서버에 연결하는 사용자는 사용자 이름 대신 SSH 키로 식별됩니다.

GitLab 서버에서 수행된 SSH 클라이언트 작업은 이 사용자로 실행됩니다. 이 SSH 구성을 수정할 수 있습니다. 예를 들어, 이 사용자에 대해 인증 요청에 사용할 개인 SSH 키를 지정할 수 있습니다. 그러나 이러한 관행은 지원되지 않으며 중대한 보안 위험을 초래하기 때문에 강력히 권장하지 않습니다.

GitLab은 이러한 조건을 확인하고, 서버가 이러한 방식으로 구성된 경우 이 섹션을 안내합니다. 예를 들어: 

$ gitlab-rake gitlab:check

Git user has default SSH configuration? ... no
  Try fixing it:
  mkdir ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
  For more information see:
  doc/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server
  Please fix the error above and rerun the checks.

가능하면 사용자 정의 구성을 즉시 제거하세요. 이러한 사용자 정의는 명시적으로 지원되지 않으며 언제든지 작동을 멈출 수 있습니다.

문제 해결

TLS: 서버가 8192비트 이상의 RSA 키를 포함한 인증서를 보냈음

GitLab 16.3 이상에서는 RSA 키를 최대 8192비트로 제한합니다. 키의 길이를 확인하려면: 

openssl rsa -in <your-key-file> -text -noout | grep "Key:"

8192비트보다 긴 키는 더 짧은 키로 바꿔야 합니다.

git clone에서 비밀번호 프롬프트

git clone을 실행할 때 git@gitlab.example.com's password:와 같이 비밀번호를 요청 받을 수 있습니다. 이는 SSH 설정에 문제가 있음을 나타냅니다.

  • SSH 키 쌍을 올바르게 생성하고 공개 SSH 키를 GitLab 프로필에 추가했는지 확인하세요.
  • ssh-agent를 사용하여 개인 SSH 키를 매뉴얼으로 등록해 보세요.
  • ssh -Tv git@example.com 명령을 실행하여 연결을 디버깅해 보세요. example.com을 사용자의 GitLab URL로 바꿔주세요.
  • 마이크로소프트 윈도우에서 SSH 사용의 모든 지침을 따랐는지 확인하세요.

Could not resolve hostname 오류

연결 가능 여부를 확인할 때 다음 오류를 받을 수 있습니다: 

ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known

이 오류가 발생하면 터미널을 재시작한 다음 명령을 다시 시도해 보세요.

Key enrollment failed: invalid format 오류

FIDO2 하드웨어 보안 키에 대한 SSH 키 쌍을 생성할 때 다음 오류를 받을 수 있습니다: 

Key enrollment failed: invalid format

다음을 시도하여 문제를 해결할 수 있습니다:

  • sudo를 사용하여 ssh-keygen 명령을 실행해 보세요.
  • FIDO2 하드웨어 보안 키가 제공된 키 유형을 지원하는지 확인해 보세요.
  • ssh -V를 실행하여 OpenSSH 버전이 8.2 이상인지 확인해 보세요.