GitHub에 SSH Key를 생성하고 등록하는 방법

Overview

GitHub에서 HTTPS 대신 SSH 방식으로 인증하려면 로컬에서 SSH 키를 생성한 뒤 공개키를 GitHub 계정에 등록해야 한다. 이 문서는 SSH 키 존재 여부 확인, 새 키 생성, 공개키 등록, 연결 확인까지 한 번에 정리한다.

1) 기존 SSH 키 확인

• 목적: 이미 사용할 수 있는 SSH 키가 있는지 먼저 확인
• 명령어:

ls -la ~/.ssh
ls ~/.ssh/*.pub

• 메모:
  • id_ed25519.pub가 있으면 이미 공개키가 생성된 상태일 가능성이 크다.
  • 키 파일 이름을 직접 바꿨다면 github_work.pub, company_key.pub처럼 다른 이름으로 보일 수 있다.
  • 공개키 파일이 하나도 없으면 아래처럼 출력될 수 있다.

ls: cannot access '/home/${USER}/.ssh/*.pub': No such file or directory

2) SSH 키 생성

• 목적: GitHub 인증에 사용할 새 SSH 키 생성
• 권장 명령어:

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

• 실행 예시:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/username/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/username/.ssh/id_ed25519
Your public key has been saved in /home/username/.ssh/id_ed25519.pub

• 메모:
  • ed25519는 현재 일반적으로 권장되는 SSH 키 알고리즘이다.
  • Enter file in which to save the key는 키 파일을 저장할 경로와 이름을 묻는 단계다.
  • 특별한 이유가 없으면 기본값인 ~/.ssh/id_ed25519를 그대로 사용하면 된다.
  • Enter passphrase는 개인키를 보호하는 비밀번호다.
  • passphrase를 비워 둘 수는 있지만, 개인 장비라도 설정해 두는 편이 더 안전하다.

3) 생성된 공개키 확인

• 목적: GitHub에 등록할 공개키 내용 확인
• 명령어:

cat ~/.ssh/id_ed25519.pub

• 예시:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKeyValue your_email@example.com

• 메모:
  • ssh-ed25519로 시작하는 한 줄 전체를 복사해야 한다.
  • 이메일 주소 같은 코멘트가 줄 끝에 있으면 그것까지 포함해서 복사한다.
  • 필요하면 아래 명령어로 키 파일 생성 여부를 같이 확인할 수 있다.

ls -la ~/.ssh

4) GitHub에 공개키 등록

• 목적: 로컬에서 만든 공개키를 GitHub 계정에 연결

• 절차:

  • GitHub 로그인 후 Settings로 이동
  • 왼쪽 메뉴에서 SSH and GPG keys 선택
  • New SSH key 버튼 선택
  • 아래 항목 입력

• 입력 값:

  • Title: 어떤 장비의 키인지 구분할 수 있는 이름
  • Key type: Git 인증 용도면 Authentication Key 선택
  • Key: 방금 복사한 공개키 전체 내용 붙여넣기

• 저장:

  • Add SSH key를 눌러 등록한다.

5) 연결 확인

• 목적: GitHub와 SSH 연결이 정상인지 확인
• 명령어:

ssh -T git@github.com

• 처음 접속하면 호스트 확인 메시지가 나올 수 있다.

The authenticity of host 'github.com (IP_ADDRESS)' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

• 이때 표시된 fingerprint가 GitHub 공식 fingerprint와 일치하는지 먼저 확인한다.
  • Ed25519: SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU
• 일치하면 yes를 입력하고 계속 진행한다.
• 아래와 비슷한 메시지가 나오면 정상이다.

Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

Notes

1) passphrase를 잊어버린 경우

• SSH 키의 passphrase는 복구할 수 없다.
• 이 경우 기존 키를 계속 풀어서 쓰는 방법은 없고, 새 키를 다시 만들어 등록해야 한다.
• 일반적인 처리 순서는 아래와 같다.
  • GitHub의 Settings > SSH and GPG keys에서 기존 공개키 삭제
  • 로컬에서 새 SSH 키 생성
  • 새 공개키를 다시 GitHub에 등록

2) 기존 id_rsa 키가 있어도 바로 교체할 필요는 없다

• 이미 id_rsa 기반 SSH 연결을 사용 중이라면 당장 문제는 없다.
• 새로 만들 때는 ed25519를 우선 고려하면 된다.
• 여러 키를 함께 관리해야 하면 ~/.ssh/config로 저장소별 키를 분리할 수 있다.