SSH Key

GitHub나 GitLab을 처음 사용할 때는 주로 ID/비밀번호 기반 인증과 SSH Key 기반 인증이라는 두 가지 방식을 접하게 됩니다. 초반에는 비밀번호 방식이 직관적이고 익숙하게 느껴질 수 있지만, 실제 개발 환경에서는 매번 비밀번호를 입력할 필요가 없고 토큰 만료나 인증 오류가 적으며 서버·CI·자동화 환경에서도 안정적으로 동작하는 SSH Key 방식이 더 널리 사용됩니다. 이러한 이유로 대부분의 실무 환경에서는 SSH 기반 인증을 기본으로 채택하고 있습니다.

SSH Key 인증의 핵심은 공개키와 개인키로 이루어진 비대칭 키 구조에 있습니다. 개인키는 사용자 로컬 환경에만 보관되는 일종의 열쇠이며, 공개키는 GitHub나 GitLab과 같은 서버에 등록되는 자물쇠에 해당합니다. 인증 과정에서 서버는 사용자가 해당 개인키를 실제로 소유하고 있는지만 검증할 뿐, 개인키 자체를 요구하거나 전달받지 않습니다.

이러한 구조 덕분에 비밀번호를 네트워크를 통해 주고받을 필요가 없어 보안성이 높으며, 자동화된 환경에서도 안전한 인증이 가능합니다. 이때 SSH Key를 생성하는 역할을 하는 명령어가 ssh-keygen이고, 생성된 개인키를 SSH 에이전트에 등록해 실제 인증 과정에서 사용 가능하도록 하는 명령어가 ssh-add입니다.

SSH Key 생성하기

SSH Key 기반 인증을 사용하려면 먼저 공개키와 개인키 한 쌍을 생성해야 합니다. 이때 사용하는 명령어가 ssh-keygen이며, 키 생성 시 어떤 암호화 알고리즘을 선택할지 결정하는 것이 중요합니다. 현재 대부분의 개발 환경에서는 ed25519 알고리즘 사용이 권장됩니다. ed25519는 최신 타원곡선 암호(ECC) 기반 알고리즘으로, 짧은 키 길이에도 불구하고 높은 보안성과 빠른 성능을 제공하며 설정 실수 가능성이 적다는 장점이 있습니다. 특별한 호환성 이슈가 없다면 기본 선택으로 충분합니다.

ssh-keygen -t ed25519 -C "your_email@example.com"

위 명령어를 실행하면 키를 저장할 경로와 패스프레이즈 설정 여부를 묻게 되며, 별도의 경로를 지정하지 않을 경우 기본적으로 ~/.ssh/ 디렉터리에 다음과 같은 파일이 생성됩니다.

id_ed25519 : 개인키 (private key)
id_ed25519.pub : 공개키 (public key)

개인키는 로컬 환경에만 보관해야 하며, 절대 외부로 공유해서는 안 됩니다. 공개키는 GitHub나 GitLab과 같은 외부 서비스에 등록하여 인증에 사용합니다. 만약 오래된 서버나 레거시 시스템 등 ed25519를 지원하지 않는 환경과의 호환성이 필요하다면 RSA 알고리즘을 선택할 수 있습니다. 이 경우에는 충분한 보안 수준을 확보하기 위해 4096비트 키 길이를 사용하는 것이 일반적입니다.

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

RSA 키를 생성하면 동일한 위치에 다음 파일이 생성됩니다.

id_rsa : 개인키 (private key)
id_rsa.pub : 공개키 (public key)

마지막으로, 하나의 환경에서 여러 개의 SSH Key를 관리해야 하는 경우에는 -f 옵션을 사용해 키 파일명을 직접 지정할 수 있습니다. 예를 들어 GitHub와 GitLab, 혹은 회사용과 개인용 키를 분리하고 싶을 때 다음과 같이 생성할 수 있습니다.

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_github -C "github@example.com"

이 경우 다음과 같은 파일이 생성됩니다.

id_ed25519_github : 개인키
id_ed25519_github.pub : 공개키

이처럼 키 파일명을 명확히 지정해 두면 이후 ~/.ssh/config 설정이나 ssh-add 사용 시에도 어떤 키를 사용하는지 쉽게 관리할 수 있습니다.

ssh-agent에 개인키 저장하기

SSH Key를 생성하고 공개키를 외부 서비스에 등록했다면, 다음 단계는 생성한 개인키를 ssh-agent에 저장하는 과정입니다. ssh-agent는 개인키를 메모리에 보관하며, 실제 SSH 인증이 발생할 때마다 해당 키를 대신 사용해 주는 역할을 합니다. 이를 통해 Git 명령을 실행할 때마다 개인키의 패스프레이즈를 반복해서 입력하지 않아도 됩니다.

여러 개의 SSH Key를 사용하는 경우에는 각각의 개인키를 ssh-agent에 개별적으로 등록할 수 있습니다. 앞에서 -f 옵션을 사용해 키 파일명을 지정했다면, 다음과 같이 생성한 키들을 하나씩 추가할 수 있습니다.

ssh-add ~/.ssh/id_ed25519_github
ssh-add ~/.ssh/id_ed25519_gitlab
ssh-add ~/.ssh/id_ed25519_company

개인키를 모두 추가한 후에는 현재 ssh-agent에 어떤 키들이 등록되어 있는지 확인하는 것이 좋습니다. 다음 명령어를 실행하면 로드된 키 목록을 확인할 수 있습니다.

ssh-add -l

정상적으로 등록되었다면 아래와 같이 각 키의 해시 값과 코멘트가 출력됩니다.

256 SHA256:lc... github@example.com (ED25519)
256 SHA256:bq... gitlab@example.com (ED25519)
256 SHA256:CI... company@example.com (ED25519)

이 목록을 통해 현재 활성화된 SSH Key를 확인할 수 있으며, 여러 계정이나 저장소를 사용하는 환경에서도 어떤 키가 사용되고 있는지 명확하게 관리할 수 있습니다.

~/.ssh/config 설정하기

여러 개의 SSH Key를 사용하는 환경에서는 ssh-agent에 키를 모두 등록하더라도, 어떤 상황에서 어떤 키가 사용되는지 명확하지 않을 수 있습니다. 이때 사용하는 설정 파일이 바로 ~/.ssh/config입니다. 이 파일을 통해 호스트별로 사용할 사용자명과 SSH Key를 명시적으로 지정할 수 있습니다.

~/.ssh/config 파일은 SSH 접속 시 참조되는 설정 파일로, GitHub나 GitLab과 같은 서비스에 접근할 때 어떤 키를 사용할지 제어하는 역할을 합니다. 이를 통해 회사 계정과 개인 계정을 분리하거나, 여러 Git 서비스를 동시에 사용하는 경우에도 인증 충돌을 방지할 수 있습니다.

다음은 GitHub와 GitLab, 그리고 회사 Git 서버를 각각 다른 SSH Key로 사용하는 예시입니다.

# =========================
# GitHub - 개인 계정
# =========================
Host github.com-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes
 
 
# =========================
# GitHub - 회사 계정 1
# =========================
Host github.com-company
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_company
    IdentitiesOnly yes
 
 
# =========================
# GitHub - 회사 계정 2
# =========================
Host github.com-company2
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_company2
    IdentitiesOnly yes
 
 
# =========================
# GitLab - 개인 계정
# =========================
Host gitlab.com-personal
    HostName gitlab.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitlab
    IdentitiesOnly yes
 
 
# =========================
# 회사 내부 Git 서버
# =========================
Host company-git
    HostName git.company.com
    User git
    IdentityFile ~/.ssh/id_ed25519_company
    IdentitiesOnly yes

IdentityFile에는 해당 호스트에서 사용할 개인키 경로를 지정하며, IdentitiesOnly yes 옵션을 설정하면 ssh-agent에 등록된 다른 키들이 시도되는 것을 방지할 수 있습니다. 이는 인증 실패나 의도치 않은 계정으로의 접근을 예방하는 데 도움이 됩니다. 이와 같이 ~/.ssh/config를 설정해 두면, Git 저장소를 사용할 때 별도의 설정 없이도 자동으로 올바른 SSH Key가 선택됩니다. 특히 여러 계정이나 여러 조직의 저장소를 동시에 사용하는 개발 환경에서는 필수적인 설정이라고 볼 수 있습니다.

SSH 연결 테스트 및 Git 사용하기

~/.ssh/config 설정과 ssh-agent 등록까지 완료했다면, 실제로 SSH 인증이 정상적으로 동작하는지 확인해야 합니다. 이 단계에서는 Git 명령어 대신 ssh 명령어를 사용해 각 Host 설정이 올바른 키와 연결되는지를 테스트합니다.

앞에서 ~/.ssh/config에 정의한 Host 이름을 기준으로 다음과 같이 연결을 확인할 수 있습니다.

ssh -T git@github.com-personal
ssh -T git@github.com-company
ssh -T git@github.com-company2
ssh -T git@gitlab.com-personal
ssh -T git@company-git

설정이 정상적으로 되어 있다면 아래와 같은 메시지가 출력됩니다.

Hi <GitHub 계정명>! You've successfully authenticated, but GitHub does not provide shell access.

이 메시지는 실제 쉘 접속은 제공하지 않지만, SSH Key를 통한 인증이 성공적으로 이루어졌다는 의미입니다. 이 단계에서 오류가 발생한다면 ssh-agent에 키가 제대로 등록되어 있는지, 혹은 ~/.ssh/config의 IdentityFile 경로가 올바른지 다시 확인해야 합니다.

~/.ssh/config Host를 이용한 Git Clone

GitHub 저장소의 기본 SSH 주소는 일반적으로 다음과 같은 형태입니다.

# GitHub 개인 계정
git@github.com:organization/repository.git
 
# GitHub 회사 계정
git clone git@github.com-company:org/repository.git
git clone git@github.com-company2:org/repository.git
 
# GitLab
git clone git@gitlab.com-personal:group/repository.git

그러나 앞에서 ~/.ssh/config에 Host를 별도로 정의했다면, git@github.com 대신 설정한 Host 이름을 사용해야 합니다. 예를 들어 회사 계정이 github.com-company2로 설정되어 있다면, 저장소 클론은 다음과 같이 수행합니다.

git clone git@github.com-company2:organization/repository.git

이렇게 Host 이름만 변경해 주면, Git은 자동으로 해당 Host에 매핑된 SSH Key(id_ed25519_company2)를 사용해 인증을 수행합니다. 이를 통해 회사 계정과 개인 계정을 명확히 분리한 상태로 Git 작업을 진행할 수 있습니다.

만약 모든 설정을 완료했음에도 회사 계정으로 접근이 되지 않는 경우에는, SSH 설정 문제가 아니라 해당 저장소에 대한 권한(협업자 초대 또는 조직 권한) 이 부여되어 있는지 확인해야 합니다.

Git 사용자 정보 확인 및 설정

마지막으로 커밋과 푸시를 진행하기 전에, Git 사용자 정보(user.name, user.email)가 올바르게 설정되어 있는지 확인하는 것이 중요합니다. 이 정보는 커밋 기록에 작성자 정보로 남기 때문에, 회사 계정과 개인 계정을 분리해 사용하는 환경에서는 특히 주의가 필요합니다.

현재 저장소 기준으로 설정된 값을 확인하려면 다음 명령어를 사용합니다.

git config user.name
git config user.email

회사 저장소에서 사용할 계정 정보는 다음과 같이 설정할 수 있습니다.

git config user.name "회사계정아이디"
git config user.email "회사계정이메일"

모든 저장소에 동일하게 적용하고자 할 경우에는 --global 옵션을 사용합니다.

git config --global user.name "이름"
git config --global user.email "이메일"

이와 같이 설정하면 SSH 인증부터 Git 커밋 정보까지 일관된 계정 분리가 가능하며, 실무 환경에서 발생할 수 있는 인증 및 기록 관련 문제를 효과적으로 예방할 수 있습니다.