맥 SSH 키 생성 깃허브 연결 막힐 때 — 한 번에 해결!

맥에서 깃허브 SSH 키를 잘 생성하고 등록까지 마쳤는데, `git push`만 하려면 매번 비밀번호를 입력하라고 나와 당황스러우셨나요?

이 문제는 대부분 SSH 키가 제대로 활성화되지 않았거나, 원격 저장소 설정에 작은 오해가 있을 때 발생합니다.

이 글에서는 SSH 키 생성부터 GitHub 연결, 그리고 반복적인 비밀번호 입력 오류를 단 3단계 만에 깔끔하게 해결하는 방법을 알려드립니다.

SSH 키 생성: 빠르고 정확한 첫걸음

SSH 키는 비밀번호 없이 안전하게 통신하는 핵심 도구입니다. 맥에서 SSH 키를 생성하는 과정은 비교적 간단하지만, 정확한 단계를 따르는 것이 중요합니다. 잘못된 설정 하나가 `git push` 시 반복되는 비밀번호 입력 문제로 이어질 수 있습니다.

대부분의 경우, 기본 설정을 따르는 것이 좋습니다. 특별한 이유가 없다면 RSA 알고리즘으로 충분하며, 생성 시 별도의 파일명을 지정하지 않으면 기본 경로에 자동으로 생성됩니다. 이 과정을 통해 개인 키와 공개 키 쌍이 만들어집니다.

1. 키 생성 명령어 실행 — 터미널에서 `ssh-keygen -t rsa -b 4096 -C “your_email@example.com”` 명령어를 입력합니다. 이메일은 본인의 GitHub 계정에 사용된 이메일 주소로 대체하세요. `Enter`를 눌러 기본 경로와 파일명(`~/.ssh/id_rsa`)을 사용하고, passphrase는 필요하면 입력하되, 보통은 비워두는 것이 편리합니다.
2. 생성된 키 확인 — `ls -al ~/.ssh` 명령어를 통해 `id_rsa` (개인 키)와 `id_rsa.pub` (공개 키) 파일이 생성되었는지 확인합니다.

생성된 개인 키는 절대 외부에 노출되어서는 안 됩니다. 공개 키는 GitHub와 같은 서비스에 등록하여 본인임을 인증하는 데 사용됩니다. 이 두 키가 올바르게 생성되었는지 확인하는 것이 모든 과정의 출발점입니다.

Photo by Lee Campbell on Pexels

GitHub에 SSH 키 등록 및 연결 확인

SSH 키를 생성했다면, 이제 이 키를 GitHub에 등록하여 맥과 GitHub 간의 안전한 연결을 설정해야 합니다. 이 단계가 제대로 이루어지지 않으면, GitHub는 여러분의 접속을 인가하지 않아 문제가 발생할 수 있습니다.

공개 키를 GitHub 계정에 추가하는 것은 아주 간단한 작업입니다. 터미널에서 `cat ~/.ssh/id_rsa.pub` 명령어를 사용하여 출력된 키 내용을 처음부터 끝까지 빠짐없이 복사하는 것이 중요합니다. 작은 공백이나 누락도 오류의 원인이 될 수 있습니다. 이 과정은 약 1분 정도면 완료됩니다.

1. 공개 키 내용 복사 — `pbcopy < ~/.ssh/id_rsa.pub` 명령어를 사용하여 공개 키 내용을 클립보드에 복사합니다.
2. GitHub에 키 등록 — GitHub 웹사이트에 로그인 후, `Settings > SSH and GPG keys > New SSH key`로 이동하여 복사한 키를 붙여넣고 적절한 제목을 입력한 뒤 `Add SSH key`를 클릭합니다.
3. SSH 연결 테스트 — 터미널에서 `ssh -T git@github.com` 명령어를 실행하여 연결을 테스트합니다. “Hi [YourUsername]! You’ve successfully authenticated…” 메시지가 보인다면 성공입니다. 만약 경고 메시지가 나온다면, `yes`를 입력하여 호스트를 신뢰합니다. 이 테스트는 문제 해결의 80% 이상을 차지하는 중요한 단계입니다.

`git push` 비밀번호 반복 입력 오류, 근본 원인과 해결

SSH 키를 생성하고 GitHub에 등록까지 마쳤는데도 `git push` 시 계속 비밀번호를 요구하는 상황은 많은 개발자를 당황하게 만듭니다. 이 문제는 대부분 SSH 에이전트(ssh-agent)가 제대로 작동하지 않거나, 원격 저장소 URL이 잘못 설정되었을 때 발생합니다.

`git remote -v` 명령어를 통해 현재 사용 중인 원격 저장소 URL을 확인하는 것이 첫 번째 해결 단계입니다. 만약 URL이 `https://github.com/YourUsername/YourRepo.git` 형태로 되어 있다면, 이것이 비밀번호 반복 입력의 직접적인 원인입니다. SSH 키 인증은 `git@github.com:YourUsername/YourRepo.git` 형태의 SSH URL을 통해서만 작동합니다.

이 문제를 해결하려면 두 가지 핵심 조치가 필요합니다. 첫째, `eval “$(ssh-agent -s)”`와 `ssh-add -K ~/.ssh/id_rsa` 명령어를 사용하여 SSH 키를 에이전트에 추가해야 합니다. 둘째, 로컬 저장소의 원격 URL을 `git remote set-url origin git@github.com:YourUsername/YourRepo.git` 명령어를 통해 SSH 방식으로 변경해야 합니다. 이 2가지 조치만으로 99%의 `git push` 비밀번호 입력 문제를 해결할 수 있습니다.

SSH 에이전트 자동 실행 설정으로 편리함 더하기

앞서 `ssh-agent`에 키를 추가하는 과정을 거쳤지만, 이 설정은 터미널 세션을 닫으면 초기화됩니다. 매번 새로운 세션을 열 때마다 다시 키를 추가하는 것은 비효율적입니다. 맥에서는 `~/.ssh/config` 파일을 활용하여 SSH 에이전트를 영구적으로 유지하고 키를 자동으로 로드하도록 설정할 수 있습니다.

`~/.ssh/config` 파일을 생성하거나 수정하여 SSH 설정을 최적화하면, 마치 마법처럼 SSH 인증 과정이 훨씬 매끄러워집니다. 이 파일은 SSH 클라이언트의 동작 방식을 제어하며, 특히 `UseKeychain yes` 옵션은 맥OS의 키체인과 연동되어 개인 키를 안전하게 보관하고 자동으로 인증하는 데 큰 도움을 줍니다.

이제 `~/.ssh/config` 파일에 아래 내용을 추가하고 저장하여, 재부팅 후에도 SSH 키가 자동으로 인식되도록 만드세요. 터미널을 열고 `nano ~/.ssh/config` 명령어를 실행한 뒤 아래 내용을 붙여넣고 저장하면 됩니다. 변경 사항 적용을 위해 터미널을 다시 시작하는 것이 좋습니다.

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_rsa

(참고: `IdentityFile`은 여러분의 개인 키 파일 경로를 지정합니다. `id_rsa` 대신 다른 이름으로 생성했다면 해당 이름으로 변경해야 합니다.)