GitHub SSH 키 등록 가이드
GitHub 계정에 SSH 키를 등록하여 저장소를 복제하거나 인증할 때 매번 비밀번호를 입력하지 않는 방법을 안내합니다.
📋 개요
**SSH (Secure Shell)**는 네트워크를 통해 비밀번호를 보내지 않고도 안전한 인증을 제공하는 프로토콜입니다. SSH 키 쌍을 GitHub에 등록하면 자격 증명을 매번 입력하지 않고도 저장소를 복제, 풀, 푸시할 수 있습니다.
GitHub는 두 가지 유형의 SSH 키를 지원합니다:
- Ed25519 (권장) — 현대적이며 안전하고 키 크기가 작습니다
- RSA (4096비트) — 레거시 호환용, Ed25519가 지원되지 않는 환경에서만 사용하세요
🛠️ 설정 단계
1. 기존 SSH 키 확인
새 키를 생성하기 전에 이미 키가 있는지 확인합니다.
Linux / macOS / WSL:
ls -la ~/.ssh/Windows (PowerShell):
Get-ChildItem $env:USERPROFILE\.sshid_ed25519, id_ed25519.pub, id_rsa, id_rsa.pub 파일이 있는지 확인합니다. 사용할 키 쌍이 이미 있으면 3단계로 건너뛰세요.
2. 새 SSH 키 생성
Ed25519 알고리즘을 사용해 새 SSH 키를 생성합니다 (권장).
Linux / macOS / WSL:
ssh-keygen -t ed25519 -C "<your-email@example.com>"Windows (PowerShell):
ssh-keygen -t ed25519 -C "<your-email@example.com>"키 파일 위치를 묻는 프롬프트에서 Enter를 눌러 기본값(~/.ssh/id_ed25519)을 적용합니다.
암호(passphrase)를 묻는 프롬프트에서는 안전한 암호를 입력하거나 Enter를 눌러 비워둘 수 있습니다. 암호를 사용하면 개인 키가 유출되더라도 추가 보안 계층이 적용됩니다.
3. 공개 키 확인 및 복사
공개 키를 표시하고 클립보드에 복사합니다.
Linux / macOS / WSL:
cat ~/.ssh/id_ed25519.pubWindows (PowerShell):
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub공개 키는 ssh-ed25519 또는 ssh-rsa로 시작하고 이메일 주소로 끝납니다. 전체 출력을 선택하여 복사하세요.
⚠️ 보안 주의: 개인 키(
id_ed25519또는id_rsa,.pub없이)를 절대 공유하거나 게시하지 마세요. 공개 키(id_ed25519.pub)만 공유해도 안전합니다.
4. GitHub에 키 등록
- GitHub에 로그인합니다
- 프로필 사진 클릭 → Settings 클릭
- 왼쪽 사이드바에서 SSH and GPG keys 클릭
- New SSH key 클릭
- Title 필드에 설명이 포함된 레이블을 입력합니다 (예:
내 노트북,사무실 PC) - Key 필드에 공개 키를 붙여넣습니다
- Add SSH key 클릭
5. 연결 테스트
SSH 키가 올바르게 등록되었는지 확인합니다.
ssh -T git@github.com첫 연결 시 다음과 같은 경고가 표시될 수 있습니다:
The authenticity of host 'github.com (IP 주소)' can't be established.
RSA key fingerprint is SHA256:xxxxx.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
yes를 입력하고 Enter를 누르세요. 성공하면 다음 메시지가 표시됩니다:
Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.
6. SSH로 저장소 복제
연결을 확인한 후 SSH 주소를 사용하여 저장소를 복제합니다.
git clone git@github.com:<owner>/<repository>.git<owner>를 저장소 소유자로, <repository>를 저장소 이름으로 대체하세요.
🔍 SSH 키 등록 확인
GitHub 계정에 등록된 모든 SSH 키를 목록으로 보려면:
- Settings → SSH and GPG keys로 이동합니다
- 제목과 생성 날짜와 함께 등록된 키 목록을 확인합니다
🩺 문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
Permission denied (publickey) | SSH 키가 등록되지 않았거나 잘못된 키 사용 | 공개 키가 GitHub에 등록되어 있는지 확인합니다. 올바른 개인 키를 사용하고 있는지 확인합니다. |
ssh -T는 "successfully authenticated"라고 하지만 git 작업은 실패 | 키가 특정 저장소에 추가되지 않음 | SSH 키가 해당 저장소에 대한 읽기/쓰기 권한이 있는지 확인합니다. |
| 연결 시간 초과 | 포트 22를 차단하는 방화벽 또는 네트워크 문제 | 네트워크 설정을 확인하거나 HTTPS를 대신 사용합니다. |
git@github.com: Permission denied | 잘못된 원격지 URL 형식 | 원격지 URL에서 git@github.com:(콜론)을 사용하고 https://github.com/이 아닌지 확인합니다. |
| "Too many authentication failures" | 키 시도 횟수가 많아 서버가 거부 | ssh -vT git@github.com으로 디버깅하거나 -i ~/.ssh/id_ed25519로 키를 지정합니다. |
🔒 보안 모범 사례
- 개인 키(
id_ed25519또는id_rsa)를 절대 공유하지 마세요. 이슈, 이메일 첨부, 저장소 커밋에 포함하지 마세요. - SSH 키 생성 시 암호(passphrase)를 사용하여 개인 키가 유출되더라도 보호하세요.
- 기기별로 고유한 SSH 키 사용 — 노트북, 데스크톱, 서버에 서로 다른 키를 등록하세요.
- 등록된 키 정기 감사 — 오래되거나 사용하지 않는 SSH 키는 GitHub 계정에서 제거하세요.
- 조직에서 중앙 집중식 키 관리가 필요한 경우 SSH 인증서 사용을 고려하세요.
📚 참조
버전: 1.0
최종 업데이트: 2026-09-24
소스 파일: giipv3/public/help/github-ssh-key.ko.md