Git을 설치하고 커밋까지는 했는데, push/pull 할 때마다 비밀번호를 묻거나, 갑자기 Permission denied (publickey)가 터지면 흐름이 끊깁니다.
이 글은 macOS 기준으로 GitHub SSH Key 세팅을 “처음부터 끝까지” 한 번에 정리한 가이드예요. 설정이 끝나면 터미널/VSCode 어디서든 GitHub SSH Key로 비밀번호 없이 push/pull 이 됩니다.
GitHub SSH Key 세팅이 필요한 이유 (HTTPS vs SSH)
HTTPS는 토큰/비밀번호를 자주 요구하고, 토큰 만료/권한 갱신 이슈가 생각보다 자주 납니다. 반면 GitHub SSH Key는 한 번만 제대로 잡아두면, 이후에는 키로 서명하듯 인증해서 push/pull 속도가 안정적이고, 자동화(CI/서버 배포)에도 유리합니다.
- 이럴 때 특히 추천: VSCode에서 자주 push/pull, 서버(원격)에서 git 사용, 여러 레포를 매일 다룸
- 자주 막히는 지점: 키가 여러 개일 때, ssh-agent 미등록, known_hosts 충돌, 레포 URL이 https로 남아있음
10분 컷: GitHub SSH Key 세팅(맥) 단계별 체크리스트
1) SSH 키 생성 (ed25519 추천)
아래 명령으로 키를 만들고, 파일명은 기본값을 그대로 써도 됩니다. 패스프레이즈(passphrase)는 “보안 강화용”이라 선택 사항이지만, 회사/중요 레포면 설정을 권장합니다.
ssh-keygen -t ed25519 -C "your_email@example.com"- 생성 위치(기본):
~/.ssh/id_ed25519, 공개키:~/.ssh/id_ed25519.pub - 핵심: GitHub에는 .pub(공개키)만 등록합니다.
2) ssh-agent 실행 & 키 등록 (macOS Keychain 연동)
여기서 삐끗하면 GitHub SSH Key를 만들어도 계속 비밀번호/패스프레이즈를 묻게 됩니다. 아래대로 진행해 주세요.
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
만약 옵션이 동작하지 않거나 오래된 macOS 환경이면, ssh-add ~/.ssh/id_ed25519로 먼저 등록 후
Keychain 저장 여부를 확인해도 됩니다.
3) 공개키 복사 → GitHub에 등록
pbcopy < ~/.ssh/id_ed25519.pubGitHub → Settings → SSH and GPG keys → “New SSH key”에서 붙여넣기 후 저장합니다. (등록 후 바로 테스트까지 이어가면, 이후 오류를 크게 줄일 수 있어요.)
4) 연결 테스트 (가장 중요)
ssh -T git@github.com- 성공 예시: “Hi username! You've successfully authenticated…”
- 실패하면: 아래 “권한 오류 Top 7”에서 해당 증상을 바로 찾으면 됩니다.
5) 레포 URL을 SSH로 바꾸기 (HTTPS 남아있으면 계속 인증 요구)
현재 원격 주소를 확인하고, https면 ssh로 변경하세요.
git remote -v
git remote set-url origin git@github.com:USERNAME/REPO.git
git remote -v이제부터는 GitHub SSH Key로 push/pull 할 때 비밀번호 없이 진행됩니다.
권한 오류 Top 7: 증상 → 원인 → 해결 (표로 한 번에)
| 증상(에러 메시지) | 가장 흔한 원인 | 바로 적용 해결 |
|---|---|---|
| Permission denied (publickey) | GitHub에 공개키 미등록 / 다른 키를 들고 감 / ssh-agent에 키 없음 |
|
| Host key verification failed | known_hosts 충돌(이전 키 기록) / 중간에 네트워크 변경 |
ssh-keygen -R github.com 후다시 ssh -T git@github.com 실행
|
| WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED | known_hosts에 저장된 호스트 키와 현재 키가 다름 |
ssh-keygen -R github.com(그래도 남으면 ~/.ssh/known_hosts에서 github.com 줄만 제거)
|
| Could not open a connection to your authentication agent | ssh-agent가 꺼짐 / 세션이 새로 열림 |
eval "$(ssh-agent -s)" 후ssh-add --apple-use-keychain ~/.ssh/id_ed25519
|
| Repository not found | 레포 URL 오타 / 권한 없는 레포 / org SSO 미승인 |
|
| fatal: Could not read from remote repository | SSH는 되는데 레포 권한이 없음 / origin이 https로 남아있음 |
git remote set-url origin git@github.com:USER/REPO.git이후 push 재시도 |
| Enter passphrase for key ... (매번 뜸) | Keychain/ssh-agent 저장이 안 됨 |
ssh-add --apple-use-keychain ~/.ssh/id_ed25519그리고 터미널을 완전히 재시작 후 재확인 |
키가 여러 개인 사람(회사/개인 분리) 필수: ~/.ssh/config 예시
회사/개인 계정, 혹은 레포별 키를 나눠 쓰면 GitHub SSH Key가 꼬이는 경우가 많습니다.
아래처럼 ~/.ssh/config로 “어떤 호스트에 어떤 키를 쓸지” 고정해 두면 안정적이에요.
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519
AddKeysToAgent yes
UseKeychain yes
이후 ssh -T git@github.com로 정상 인증되는지 다시 확인하세요.
VSCode에서만 안 될 때 체크 3가지
- 내장 터미널 쉘: VSCode 터미널에서
ssh -T git@github.com가 되는지 먼저 확인 - 원격 URL: VSCode 소스제어는 origin이 https면 다시 인증을 요구할 수 있음 → SSH로 변경
- 키체인/에이전트: VSCode를 먼저 켜둔 상태에서 키 등록이 안 잡힌 경우가 있어, VSCode 재시작이 빠른 해결책
바로 적용 CTA
이 글대로 했는데도 계속 막힌다면, 아래 2가지만 다시 확인하면 해결되는 경우가 많습니다: (1) ssh -T가 성공하는지, (2) origin이 SSH인지.
FAQ (자주 묻는 질문)
정리하면, GitHub SSH Key 세팅은 “키 생성 → 에이전트 등록 → GitHub 등록 → ssh -T 테스트 → 원격 URL SSH 변경” 5단계만 확실히 하면 끝입니다. 막히면 표의 Top 7에서 메시지 그대로 찾아서 순서대로만 적용해 보세요.
0 댓글