GitLab과 통신하기 위한 SSH 키 사용

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

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

GitLab은 SSH 프로토콜을 사용하여 Git과 안전하게 통신합니다. SSH 키를 사용하여 GitLab 원격 서버에 인증할 때마다 사용자 이름과 비밀번호를 입력할 필요가 없습니다.

SSH 키란 무엇인가요

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

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

공개 키를 업로드하여 기밀 데이터를 노출하는 것은 불가능합니다. SSH 공개 키를 복사하거나 업로드해야 할 때는, 실수로 개인 키를 복사하거나 업로드하지 않도록 주의하십시오.

개인 키를 사용하여 커밋 서명하기를 할 수 있으며, 이로 인해 GitLab과 데이터를 더욱 안전하게 사용할 수 있습니다. 이 서명은 귀하의 공개 키를 사용하는 누구나 검증할 수 있습니다.

자세한 내용은 비대칭 암호학, 즉 공개 키 암호학을 참조하십시오.

필수 조건

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 키

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

사용 가능한 문서에서는 ED25519가 RSA보다 더 안전하다고 제안합니다.

RSA 키를 사용하는 경우, 미국 국립 표준 기술 연구소(NIST)에서는 Publication 800-57 Part 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 "<comment>"

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 "<comment>"

    ECDSA_SK의 경우:

    ssh-keygen -t ecdsa-sk -C "<comment>"

    보안 키가 FIDO2 거주 키를 지원하는 경우, SSH 키를 생성할 때 이를 활성화할 수 있습니다:

    ssh-keygen -t ed25519-sk -O resident -C "<comment>"

    -O resident는 키가 FIDO 인증기 자체에 저장되어야 함을 나타냅니다. 거주 키는 보안 키에서 직접 로드할 수 있기 때문에 새로운 컴퓨터로 가져오기가 더 쉽습니다 ssh-add -K 또는 ssh-keygen -K로 로드할 수 있습니다.

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

    public/private ed25519-sk 키 쌍을 생성하는 중입니다.
키 생성을 승인하려면 인증기를 터치해야 할 수 있습니다.

  5. 하드웨어 보안 키의 버튼을 터치합니다.

  6. 제안된 파일 이름과 디렉터리를 수락합니다:

    Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk):

  7. 암호 구문을 지정합니다:

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

    확인 메시지가 표시되며, 파일이 저장된 위치에 대한 정보도 포함됩니다.

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

비밀번호 관리자를 사용하여 SSH 키 쌍 생성

1Password를 사용하여 SSH 키 쌍 생성

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

  • 새 SSH 키를 자동으로 생성합니다.
  • GitLab과 인증하기 위해 1Password 자산에 있는 기존 SSH 키를 사용합니다.

  1. GitLab에 로그인합니다.

  2. 왼쪽 사이드바에서 아바타를 선택합니다.

  3. 프로필 편집을 선택합니다.

  4. 왼쪽 사이드바에서 SSH 키를 선택합니다.

  5. 새 키 추가를 선택합니다.

  6. 키를 선택하면 1Password 도우미가 나타납니다.

  7. 1Password 아이콘을 선택하고 1Password를 잠금 해제합니다.

  8. 그런 다음 SSH 키 생성을 선택하거나 기존 SSH 키를 선택하여 공개 키를 채웁니다.

  9. 제목 상자에 Work Laptop 또는 Home Workstation과 같은 설명을 입력합니다.

  10. 선택 사항. 키의 사용 유형을 선택합니다. 인증(Authentication) 또는 서명(Signing) 또는 둘 다 사용될 수 있습니다. 인증 및 서명이 기본값입니다.

  11. 선택 사항. 기본 만료 날짜를 수정하려면 만료 날짜를 업데이트합니다.

  12. 키 추가를 선택합니다.

SSH 키와 함께 1Password를 사용하는 방법에 대한 자세한 내용은 1Password 문서를 참조하세요.

GitLab 계정에 SSH 키 추가하기

  • GitLab 15.4에서 도입된 키에 대한 기본 만료 날짜 제안.
  • GitLab 15.7에서 추가된 SSH 키의 사용 유형.

GitLab에서 SSH를 사용하려면 공개 키를 GitLab 계정에 복사합니다:

  1. 공개 키 파일의 내용을 복사합니다. 수동으로 하거나 스크립트를 사용할 수 있습니다.
    예를 들어, ED25519 키를 클립보드에 복사하려면:

    macOS

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

    Linux (xclip 패키지가 필요함)

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

    Windows의 Git Bash

    cat ~/.ssh/id_ed25519.pub | clip

    id_ed25519.pub를 파일 이름으로 바꿉니다. 예를 들어, 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. 제목 상자에 Work Laptop 또는 Home Workstation과 같은 설명을 입력합니다.

  9. 선택 사항. 키의 사용 유형을 선택합니다. Authentication 또는 Signing 또는 둘 다에 사용할 수 있습니다. 기본값은 Authentication & Signing입니다.

  10. 선택 사항. 기본 만료 날짜를 수정하려면 만료 날짜를 업데이트합니다.
    • 관리자는 만료 날짜를 보고 키 삭제 시 참고할 수 있습니다.
    • GitLab은 매일 오전 1시(UTC)에 모든 SSH 키를 확인합니다.
      만료가 7일 남은 모든 SSH 키에 대해 만료 알림을 이메일로 발송합니다.
    • GitLab은 매일 오전 2시(UTC)에 모든 SSH 키를 확인합니다.
      현재 날짜에 만료되는 모든 SSH 키에 대해 만료 알림을 이메일로 발송합니다.
  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입니다.

  2. 터미널을 열고 이 명령을 실행합니다. gitlab.example.com을 귀하의 GitLab 인스턴스 URL로 바꿉니다:

    ssh -T git@gitlab.example.com

  3. 처음으로 연결하는 경우 GitLab 호스트의 진위성을 확인해야 합니다.
    다음과 같은 메시지가 표시되면:

    호스트 'gitlab.example.com (35.231.145.151)'의 진위가 확인되지 않았습니다.
ECDSA 키 지문은 SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw입니다.
계속 연결하시겠습니까 (예/아니요)? 예
경고: 'gitlab.example.com' (ECDSA)을(를) 알려진 호스트 목록에 영구적으로 추가했습니다.

    예를 입력하고 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 Agent를 사용하지 않으며 Git 2.10 이상이 필요합니다. ssh 명령 옵션에 대한 더 많은 정보는 ssh 및 ssh_config의 man 페이지를 참조하세요.

계정의 SSH 키 보기

계정의 SSH 키를 보려면:

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

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

  • 키의:
    • 이름.
    • 공개 지문.
    • 만료 날짜.
    • 허용된 사용 유형.
  • 키가 마지막으로 사용된 시간.

SSH 키 삭제

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

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

단일 GitLab 인스턴스에서 서로 다른 계정 사용

단일 GitLab 인스턴스에 연결하기 위해 여러 계정을 사용할 수 있습니다.
이렇게 하려면 이전 주제에 있는 명령을 사용하세요.
그러나 IdentitiesOnly를 yes로 설정하더라도 Host 블록 외부에 IdentityFile이 존재하는 경우 로그인할 수 없습니다.

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

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

# User2 계정 신원
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을 사용하고 있다면, git과 ssh가 미리 설치된 Windows Subsystem for Linux (WSL)와 WSL 2를 사용할 수 있거나, Git for Windows를 설치하여 PowerShell을 통해 SSH를 사용할 수 있습니다.

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 사용자에게 기본 SSH 구성 있습니까? ... 아니요
  이를 수정해보세요:
  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
  자세한 정보는 다음을 참조하세요:
  doc/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server
  위의 오류를 수정하고 체크를 다시 실행하세요.

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

GitLab SSH 소유권 및 권한 확인

GitLab SSH 폴더 및 파일은 다음과 같은 권한을 가져야 합니다:

  • /var/opt/gitlab/.ssh/ 폴더는 git 그룹과 git 사용자 소유이며, 권한은 700으로 설정되어 있어야 합니다.
  • authorized_keys 파일은 권한이 600으로 설정되어야 합니다.
  • authorized_keys.lock 파일은 권한이 644로 설정되어야 합니다.

이러한 권한이 올바른지 확인하려면 다음 명령어를 실행하세요:

stat -c "%a %n" /var/opt/gitlab/.ssh/.

권한 설정

권한이 잘못된 경우, 애플리케이션 서버에 로그인하고 다음을 실행하세요:

cd /var/opt/gitlab/
chown git:git /var/opt/gitlab/.ssh/
chmod 700  /var/opt/gitlab/.ssh/
chmod 600  /var/opt/gitlab/.ssh/authorized_keys
chmod 644  /var/opt/gitlab/.ssh/authorized_keys.lock