GitLab에서 SSH 키 사용

요약

SSH 키를 사용하면 코드를 푸시하거나 풀할 때마다 사용자 이름과 비밀번호를 입력하지 않고도 GitLab에 안전하게 인증할 수 있습니다. GitLab에서 SSH 키를 사용하려면 다음을 수행해야 합니다: 그런 다음 SSH로 리포지터리를 클론할 수 있습니다.

SSH 키를 사용하면 코드를 푸시하거나 풀할 때마다 사용자 이름과 비밀번호를 입력하지 않고도 GitLab에 안전하게 인증할 수 있습니다.

GitLab에서 SSH 키를 사용하려면 다음을 수행해야 합니다:

로컬 시스템에서 SSH 키 쌍을 생성합니다.
GitLab 계정에 SSH 키를 추가합니다.
GitLab 연결을 확인합니다.

그런 다음 SSH로 리포지터리를 클론할 수 있습니다. SSH 키 하나로 계정이 접근할 수 있는 모든 프로젝트와 그룹에 인증됩니다. 프로젝트마다 별도의 키가 필요하지 않습니다. 특정 리포지터리에 다른 키를 사용하려면 리포지터리별로 다른 키 사용을 참고합니다.

Note

하드웨어 보안 키, 다중 계정, Microsoft Windows 등 덜 일반적인 구성은 고급 SSH 키 구성을 참고합니다.

SSH 키 개요#

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

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

공개 키를 업로드해도 기밀 데이터가 노출되지 않습니다. SSH 공개 키를 복사하거나 업로드할 때는 개인 키를 실수로 복사하거나 업로드하지 않도록 주의합니다.

개인 키로 커밋에 서명할 수 있으며, 이를 통해 GitLab 사용과 데이터를 한층 더 안전하게 보호할 수 있습니다. 이 서명은 공개 키를 사용해 누구나 검증할 수 있습니다.

자세한 내용은 공개 키 암호화라고도 하는 비대칭 암호화를 참고합니다.

사전 요구 사항#

SSH로 GitLab과 통신하려면 다음이 필요합니다:

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

Note

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

지원되는 SSH 키 유형#

GitLab과 통신할 때 다음 SSH 키 유형을 사용할 수 있습니다:

알고리즘	참고
ED25519 (권장)	RSA 키보다 안전하고 성능이 좋습니다. OpenSSH 6.5(2014)에서 도입되었으며 대부분의 운영 체제에서 사용할 수 있습니다. 일부 FIPS 시스템에서는 완전히 지원되지 않을 수 있습니다. 자세한 내용은 이슈 367429를 참고합니다.
ED25519_SK	로컬 클라이언트와 GitLab 서버 양쪽에 OpenSSH 8.2 이상이 필요합니다.
ECDSA_SK	로컬 클라이언트와 GitLab 서버 양쪽에 OpenSSH 8.2 이상이 필요합니다.
RSA	ED25519보다 안전성이 낮습니다. 사용하는 경우 GitLab은 최소 4096비트 키 크기를 권장합니다. Go의 제약으로 최대 키 길이는 8192비트입니다. 기본 키 크기는 `ssh-keygen` 버전에 따라 다릅니다.
ECDSA	DSA와 관련된 보안 문제는 ECDSA 키에도 적용됩니다.

기존 SSH 키 쌍 확인#

키 쌍을 만들기 전에 이미 키 쌍이 있는지 확인합니다.

홈 디렉터리로 이동합니다.
.ssh/ 하위 디렉터리로 이동합니다. .ssh/ 하위 디렉터리가 없다면 홈 디렉터리에 있지 않거나 ssh를 사용한 적이 없는 것입니다. 후자의 경우 SSH 키 쌍을 생성해야 합니다.

다음 형식 중 하나에 해당하는 파일이 있는지 확인합니다:

알고리즘	공개 키	개인 키
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 (최소 4096비트 키 크기)	`id_rsa.pub`	`id_rsa`
DSA (더 이상 사용되지 않음)	`id_dsa.pub`	`id_dsa`
ECDSA	`id_ecdsa.pub`	`id_ecdsa`

SSH 키 쌍 생성#

기존 SSH 키 쌍이 없으면 새로 생성합니다:

터미널을 엽니다.
키 유형과 함께 ssh-keygen -t를 실행합니다. 나중에 키를 식별하기 쉽도록 주석을 덧붙일 수 있습니다. 주석에는 이메일 주소를 사용하는 방식이 일반적입니다. 주석은 .pub 파일에 포함됩니다.

예를 들어 ED25519의 경우:
```
ssh-keygen -t ed25519 -C "<comment>"
```
4096비트 RSA의 경우:
```
ssh-keygen -t rsa -b 4096 -C "<comment>"
```

Enter를 누릅니다. 다음과 비슷한 출력이 표시됩니다:

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

배포 키를 생성하거나 다른 키를 보관하는 특정 디렉터리에 저장하려는 경우가 아니면, 제안된 파일 이름과 디렉터리를 그대로 사용합니다.

SSH 키 쌍을 특정 호스트 전용으로 지정할 수도 있습니다.
패스프레이즈를 지정합니다:
```
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```
파일이 저장된 위치를 포함한 확인 메시지가 표시됩니다. 공개 키와 개인 키가 생성됩니다.
개인 SSH 키를 ssh-agent에 추가합니다.

예를 들어 ED25519의 경우:
```
ssh-add ~/.ssh/id_ed25519
```

GitLab 계정에 SSH 키 추가#

GitLab에서 SSH를 사용하려면 공개 키를 GitLab 계정에 복사합니다. GitLab은 개인 키에 접근할 수 없습니다.

SSH 키를 추가하면 GitLab은 알려진 유출 키 목록과 대조합니다. 유출된 키는 연결된 개인 키가 공개되어 계정 접근에 악용될 수 있으므로 추가할 수 없습니다. 이 제한은 구성할 수 없습니다.

키가 차단되면 SSH 키 쌍을 새로 생성합니다.

GitLab 계정에 SSH 키를 추가하려면:

공개 키 파일의 내용을 복사합니다. 수동으로 복사하거나 스크립트를 사용할 수 있습니다.

다음 예시에서 id_ed25519.pub을 사용 중인 파일 이름으로 바꿉니다. 예를 들어 RSA는 id_rsa.pub을 사용합니다.

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

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

   cat ~/.ssh/id_ed25519.pub | clip

GitLab에 로그인합니다.
오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.
Add new key를 선택합니다.
Key 상자에 공개 키의 내용을 붙여 넣습니다. 키를 수동으로 복사했다면 키 전체를 복사했는지 확인합니다. 키는 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으로 시작하며 주석으로 끝날 수 있습니다.
Title 상자에 Work Laptop 이나 Home Workstation 같은 설명을 입력합니다.
선택 사항. 키의 Usage type을 선택합니다. Authentication 또는 Signing, 혹은 둘 다에 사용할 수 있습니다. 기본값은 Authentication & Signing 입니다.
선택 사항. 기본 만료일을 변경하려면 Expiration date를 수정합니다. 자세한 내용은 SSH 키 만료를 참고합니다.
Add key를 선택합니다.

SSH 연결 확인#

SSH 키가 올바르게 추가되었는지, GitLab 인스턴스에 연결할 수 있는지 확인합니다:

올바른 서버에 연결하도록 SSH 호스트 키 지문을 확인합니다:
- GitLab.com은 SSH 호스트 키 지문 문서를 참고합니다.
- GitLab Self-Managed 또는 GitLab Dedicated는 https://gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints를 참고합니다. 여기서 gitlab.example.com은 GitLab 인스턴스 URL입니다.
터미널을 열고 다음 명령을 실행합니다:
- GitLab.com은 ssh -T git@gitlab.com을 사용합니다.
- GitLab Self-Managed 또는 GitLab Dedicated는 ssh -T git@gitlab.example.com을 사용합니다. 여기서 gitlab.example.com은 GitLab 인스턴스 URL입니다.

기본적으로 연결에는 git 사용자 이름이 사용되지만, GitLab Self-Managed 또는 GitLab Dedicated 관리자는 사용자 이름을 변경할 수 있습니다.

처음 연결할 때는 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)?
```
환영 메시지가 표시됩니다.
```
Welcome to GitLab, <username>!
```
메시지가 표시되지 않으면 SSH 연결 문제를 해결할 수 있습니다.

SSH 키 보기#

계정의 SSH 키를 보려면:

오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.

기존 SSH 키가 페이지 하단에 표시됩니다. 표시되는 정보는 다음과 같습니다:

키의 제목
공개 지문
허용된 사용 유형
생성일
마지막 사용일
만료일

SSH 키 제거#

SSH 키를 취소하거나 삭제하여 계정에서 영구히 제거할 수 있습니다.

해당 키로 커밋에 서명한 경우 SSH 키 제거에는 추가적인 영향이 따릅니다. 자세한 내용은 제거된 SSH 키로 서명된 커밋을 참고합니다.

SSH 키 취소#

SSH 키가 유출되면 해당 키를 취소합니다.

사전 요구 사항:

SSH 키의 사용 유형이 Signing 또는 Authentication & Signing 이어야 합니다.

SSH 키를 취소하려면:

오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.
취소할 SSH 키 옆에서 Revoke를 선택합니다.
Revoke를 선택합니다.

SSH 키 삭제#

SSH 키를 삭제하려면:

오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.
삭제할 키 옆에서 Remove ([remove])를 선택합니다.
Delete를 선택합니다.

SSH 키 만료#

계정에 SSH 키를 추가할 때 만료일을 설정할 수 있습니다. 이 선택적 설정은 보안 침해 위험을 줄이는 데 도움이 됩니다.

SSH 키가 만료되면 더 이상 해당 키로 인증하거나 커밋에 서명할 수 없습니다. 새 SSH 키를 생성하고 계정에 추가해야 합니다.

GitLab Self-Managed 및 GitLab Dedicated에서 관리자는 만료일을 확인하고 키를 삭제할 때 참고 자료로 활용할 수 있습니다.

GitLab은 매일 만료 예정 SSH 키를 확인하고 알림을 보냅니다:

만료 7일 전 UTC 01:00.
만료일 당일 UTC 02:00.

GitLab에서 SSH 키 사용

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

SSH 키를 사용하면 코드를 푸시하거나 풀할 때마다 사용자 이름과 비밀번호를 입력하지 않고도 GitLab에 안전하게 인증할 수 있습니다.

GitLab에서 SSH 키를 사용하려면 다음을 수행해야 합니다:

로컬 시스템에서 SSH 키 쌍을 생성합니다.
GitLab 계정에 SSH 키를 추가합니다.
GitLab 연결을 확인합니다.

Note

하드웨어 보안 키, 다중 계정, Microsoft Windows 등 덜 일반적인 구성은 고급 SSH 키 구성을 참고합니다.

SSH 키 개요#

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

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

자세한 내용은 공개 키 암호화라고도 하는 비대칭 암호화를 참고합니다.

사전 요구 사항#

SSH로 GitLab과 통신하려면 다음이 필요합니다:

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

Note

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

지원되는 SSH 키 유형#

GitLab과 통신할 때 다음 SSH 키 유형을 사용할 수 있습니다:

알고리즘	참고
ED25519 (권장)	RSA 키보다 안전하고 성능이 좋습니다. OpenSSH 6.5(2014)에서 도입되었으며 대부분의 운영 체제에서 사용할 수 있습니다. 일부 FIPS 시스템에서는 완전히 지원되지 않을 수 있습니다. 자세한 내용은 이슈 367429를 참고합니다.
ED25519_SK	로컬 클라이언트와 GitLab 서버 양쪽에 OpenSSH 8.2 이상이 필요합니다.
ECDSA_SK	로컬 클라이언트와 GitLab 서버 양쪽에 OpenSSH 8.2 이상이 필요합니다.
RSA	ED25519보다 안전성이 낮습니다. 사용하는 경우 GitLab은 최소 4096비트 키 크기를 권장합니다. Go의 제약으로 최대 키 길이는 8192비트입니다. 기본 키 크기는 `ssh-keygen` 버전에 따라 다릅니다.
ECDSA	DSA와 관련된 보안 문제는 ECDSA 키에도 적용됩니다.

기존 SSH 키 쌍 확인#

키 쌍을 만들기 전에 이미 키 쌍이 있는지 확인합니다.

홈 디렉터리로 이동합니다.
.ssh/ 하위 디렉터리로 이동합니다. .ssh/ 하위 디렉터리가 없다면 홈 디렉터리에 있지 않거나 ssh를 사용한 적이 없는 것입니다. 후자의 경우 SSH 키 쌍을 생성해야 합니다.

다음 형식 중 하나에 해당하는 파일이 있는지 확인합니다:

알고리즘	공개 키	개인 키
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 (최소 4096비트 키 크기)	`id_rsa.pub`	`id_rsa`
DSA (더 이상 사용되지 않음)	`id_dsa.pub`	`id_dsa`
ECDSA	`id_ecdsa.pub`	`id_ecdsa`

SSH 키 쌍 생성#

기존 SSH 키 쌍이 없으면 새로 생성합니다:

터미널을 엽니다.
키 유형과 함께 ssh-keygen -t를 실행합니다. 나중에 키를 식별하기 쉽도록 주석을 덧붙일 수 있습니다. 주석에는 이메일 주소를 사용하는 방식이 일반적입니다. 주석은 .pub 파일에 포함됩니다.

예를 들어 ED25519의 경우:
```
ssh-keygen -t ed25519 -C "<comment>"
```
4096비트 RSA의 경우:
```
ssh-keygen -t rsa -b 4096 -C "<comment>"
```

Enter를 누릅니다. 다음과 비슷한 출력이 표시됩니다:

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

배포 키를 생성하거나 다른 키를 보관하는 특정 디렉터리에 저장하려는 경우가 아니면, 제안된 파일 이름과 디렉터리를 그대로 사용합니다.

SSH 키 쌍을 특정 호스트 전용으로 지정할 수도 있습니다.
패스프레이즈를 지정합니다:
```
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```
파일이 저장된 위치를 포함한 확인 메시지가 표시됩니다. 공개 키와 개인 키가 생성됩니다.
개인 SSH 키를 ssh-agent에 추가합니다.

예를 들어 ED25519의 경우:
```
ssh-add ~/.ssh/id_ed25519
```

GitLab 계정에 SSH 키 추가#

GitLab에서 SSH를 사용하려면 공개 키를 GitLab 계정에 복사합니다. GitLab은 개인 키에 접근할 수 없습니다.

키가 차단되면 SSH 키 쌍을 새로 생성합니다.

GitLab 계정에 SSH 키를 추가하려면:

공개 키 파일의 내용을 복사합니다. 수동으로 복사하거나 스크립트를 사용할 수 있습니다.

다음 예시에서 id_ed25519.pub을 사용 중인 파일 이름으로 바꿉니다. 예를 들어 RSA는 id_rsa.pub을 사용합니다.

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

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

   cat ~/.ssh/id_ed25519.pub | clip

GitLab에 로그인합니다.
오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.
Add new key를 선택합니다.
Key 상자에 공개 키의 내용을 붙여 넣습니다. 키를 수동으로 복사했다면 키 전체를 복사했는지 확인합니다. 키는 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으로 시작하며 주석으로 끝날 수 있습니다.
Title 상자에 Work Laptop 이나 Home Workstation 같은 설명을 입력합니다.
선택 사항. 키의 Usage type을 선택합니다. Authentication 또는 Signing, 혹은 둘 다에 사용할 수 있습니다. 기본값은 Authentication & Signing 입니다.
선택 사항. 기본 만료일을 변경하려면 Expiration date를 수정합니다. 자세한 내용은 SSH 키 만료를 참고합니다.
Add key를 선택합니다.

SSH 연결 확인#

SSH 키가 올바르게 추가되었는지, GitLab 인스턴스에 연결할 수 있는지 확인합니다:

올바른 서버에 연결하도록 SSH 호스트 키 지문을 확인합니다:
- GitLab.com은 SSH 호스트 키 지문 문서를 참고합니다.
- GitLab Self-Managed 또는 GitLab Dedicated는 https://gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprints를 참고합니다. 여기서 gitlab.example.com은 GitLab 인스턴스 URL입니다.
터미널을 열고 다음 명령을 실행합니다:
- GitLab.com은 ssh -T git@gitlab.com을 사용합니다.
- GitLab Self-Managed 또는 GitLab Dedicated는 ssh -T git@gitlab.example.com을 사용합니다. 여기서 gitlab.example.com은 GitLab 인스턴스 URL입니다.

기본적으로 연결에는 git 사용자 이름이 사용되지만, GitLab Self-Managed 또는 GitLab Dedicated 관리자는 사용자 이름을 변경할 수 있습니다.

처음 연결할 때는 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)?
```
환영 메시지가 표시됩니다.
```
Welcome to GitLab, <username>!
```
메시지가 표시되지 않으면 SSH 연결 문제를 해결할 수 있습니다.

SSH 키 보기#

계정의 SSH 키를 보려면:

오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.

기존 SSH 키가 페이지 하단에 표시됩니다. 표시되는 정보는 다음과 같습니다:

키의 제목
공개 지문
허용된 사용 유형
생성일
마지막 사용일
만료일

SSH 키 제거#

SSH 키를 취소하거나 삭제하여 계정에서 영구히 제거할 수 있습니다.

해당 키로 커밋에 서명한 경우 SSH 키 제거에는 추가적인 영향이 따릅니다. 자세한 내용은 제거된 SSH 키로 서명된 커밋을 참고합니다.

SSH 키 취소#

SSH 키가 유출되면 해당 키를 취소합니다.

사전 요구 사항:

SSH 키의 사용 유형이 Signing 또는 Authentication & Signing 이어야 합니다.

SSH 키를 취소하려면:

오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.
취소할 SSH 키 옆에서 Revoke를 선택합니다.
Revoke를 선택합니다.

SSH 키 삭제#

SSH 키를 삭제하려면:

오른쪽 위에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > SSH keys를 선택합니다.
삭제할 키 옆에서 Remove ([remove])를 선택합니다.
Delete를 선택합니다.

SSH 키 만료#

계정에 SSH 키를 추가할 때 만료일을 설정할 수 있습니다. 이 선택적 설정은 보안 침해 위험을 줄이는 데 도움이 됩니다.

SSH 키가 만료되면 더 이상 해당 키로 인증하거나 커밋에 서명할 수 없습니다. 새 SSH 키를 생성하고 계정에 추가해야 합니다.

GitLab Self-Managed 및 GitLab Dedicated에서 관리자는 만료일을 확인하고 키를 삭제할 때 참고 자료로 활용할 수 있습니다.

GitLab은 매일 만료 예정 SSH 키를 확인하고 알림을 보냅니다:

만료 7일 전 UTC 01:00.
만료일 당일 UTC 02:00.

GitLab에서 SSH 키 사용

SSH 키 개요#

사전 요구 사항#

지원되는 SSH 키 유형#

기존 SSH 키 쌍 확인#

SSH 키 쌍 생성#

GitLab 계정에 SSH 키 추가#

SSH 연결 확인#

SSH 키 보기#

SSH 키 제거#

SSH 키 취소#

SSH 키 삭제#

SSH 키 만료#

관련 주제#

GitLab에서 SSH 키 사용

SSH 키 개요#

사전 요구 사항#

지원되는 SSH 키 유형#

기존 SSH 키 쌍 확인#

SSH 키 쌍 생성#

GitLab 계정에 SSH 키 추가#

SSH 연결 확인#

SSH 키 보기#

SSH 키 제거#

SSH 키 취소#

SSH 키 삭제#

SSH 키 만료#

관련 주제#