맥에서 SSH 키를 생성하고 깃허브에 연결했는데도 여전히 push 시 비밀번호를 입력해야 하거나, 아예 연결이 되지 않아 답답했던 경험이 있으신가요? 많은 개발자들이 이 과정에서 유사한 불편함을 겪으며 시간과 에너지를 낭비하곤 합니다.
이러한 문제는 대부분 SSH 키 생성 방식의 미흡함, 깃허브 등록 과정의 누락, 또는 SSH 에이전트 설정 미비에서 비롯됩니다.
이 글에서는 맥에서 깃허브 SSH 키를 처음부터 끝까지 올바르게 생성하고 등록하며, 심지어 연결 오류까지 완벽하게 해결하는 4단계 가이드를 제시합니다. 지금 바로 안전하고 편리한 개발 환경을 구축해 보세요.
– 맥에서 Ed25519 알고리즘으로 SSH 키를 생성하는 정확한 방법을 안내합니다.
– 생성된 공개 키를 깃허브 계정에 안전하게 등록하는 과정을 상세히 설명합니다.
– SSH 에이전트 설정 및 ~/.ssh/config 파일을 통해 연결 안정성을 90% 이상 높이는 방법을 다룹니다.
– Push 시 비밀번호 입력 문제 등 흔히 발생하는 연결 오류를 효과적으로 해결하는 3가지 팁을 제공합니다.
SSH 키 생성: 깃허브 연결의 첫 단추
깃허브와 안전하게 통신하려면 SSH 키 페어(개인 키와 공개 키)를 먼저 생성해야 합니다. 여기서 중요한 점은 권장되는 암호화 방식인 Ed25519를 사용하는 것입니다. RSA 방식도 여전히 유효하지만, Ed25519는 더 높은 보안성과 효율성을 제공합니다. 이 과정을 통해 여러분의 맥에 고유한 디지털 신분증을 만드는 것과 같습니다.
SSH 키 생성은 터미널에서 간단한 명령어 하나로 시작됩니다. 키 생성 시 암호(passphrase)를 설정하는 것이 보안상 매우 중요합니다. 이 암호는 개인 키가 유출되었을 때 무단 사용을 방지하는 2차 방어선 역할을 합니다. 비밀번호를 설정하지 않으면 편리하지만, 그만큼 보안에 취약해질 수 있다는 점을 항상 기억해야 합니다.
- 터미널 열기 — Spotlight 검색(
Command + Space)을 통해 ‘터미널’을 검색하여 실행합니다. - SSH 키 생성 명령 입력 — 아래 명령어를 입력하고
your_email@example.com부분에 실제 사용하는 깃허브 계정 이메일을 넣습니다.ssh-keygen -t ed25519 -C "your_email@example.com" - 저장 경로 및 암호 설정 — 기본 경로(
~/.ssh/id_ed25519)를 사용하는 것이 일반적입니다. Enter를 눌러 기본 경로를 선택하고, 이후 암호(passphrase)를 두 번 입력합니다. 보안을 위해 8자 이상의 강력한 암호를 설정하는 것을 권장합니다. - 키 페어 확인 — 키 생성이 완료되면
~/.ssh디렉토리에id_ed25519(개인 키)와id_ed25519.pub(공개 키) 파일이 생성되었는지 확인합니다.
만약 기존에 SSH 키가 있다면, 새로운 키를 생성하기 전에 기존 키를 백업하거나 다른 이름으로 생성하는 것을 고려하세요. 기본 경로에 생성할 경우 기존 키를 덮어쓸 수 있습니다.
생성된 SSH 키 깃허브에 등록하기
이제 맥에서 생성된 공개 키(id_ed25519.pub)를 깃허브 계정에 등록할 차례입니다. 깃허브는 이 공개 키를 이용해 여러분이 SSH를 통해 접근하려는 시도가 유효한지 확인하게 됩니다. 마치 깃허브가 여러분의 자물쇠를 열 수 있는 열쇠를 가지게 되는 과정과 같습니다. 이 단계는 단 3분이면 충분합니다.
공개 키는 개인 키와 달리 외부에 공개되어도 문제가 없습니다. 이 키를 깃허브에 등록함으로써, 앞으로 해당 맥에서 깃허브 저장소에 접근할 때마다 비밀번호를 입력할 필요 없이 자동으로 인증되는 편리함을 누릴 수 있습니다.
- 공개 키 내용 복사 — 터미널에 아래 명령어를 입력하여 공개 키의 내용을 클립보드에 복사합니다.
pbcopy < ~/.ssh/id_ed25519.pub - 깃허브 접속 및 설정 이동 — 웹 브라우저를 열어 깃허브(github.com)에 로그인합니다. 오른쪽 상단의 프로필 아이콘을 클릭한 뒤, ‘Settings’로 이동합니다.
- SSH 키 등록 — 왼쪽 사이드바에서 ‘SSH and GPG keys’를 클릭합니다. ‘New SSH key’ 또는 ‘Add SSH key’ 버튼을 클릭합니다.
- 정보 입력 및 키 붙여넣기 — ‘Title’ 필드에 이 키를 식별할 수 있는 이름(예: ‘My Mac Pro’)을 입력합니다. ‘Key’ 필드에 클립보드에 복사해둔 공개 키 내용을 붙여넣습니다. ‘Add SSH key’ 버튼을 클릭하여 등록을 완료합니다.
Photo by Tranmautritam on Pexels
SSH 에이전트 설정 및 연결 확인
SSH 키를 깃허브에 등록했다고 해서 모든 과정이 끝나는 것은 아닙니다. 맥의 SSH 에이전트가 여러분의 개인 키를 관리하고, 깃허브와 통신할 때 이를 사용하도록 설정해야 합니다. 이 과정은 일종의 ‘열쇠 지킴이’를 설정하는 것과 같으며, 매번 키 암호를 입력해야 하는 번거로움을 줄여줍니다.
특히 ~/.ssh/config 파일을 적절히 설정하면, 깃허브 연결 시 특정 개인 키를 사용하도록 명시하여 예상치 못한 인증 문제를 90% 이상 방지할 수 있습니다. 이는 여러 개의 SSH 키를 사용하는 환경에서 더욱 빛을 발합니다.
- SSH 에이전트에 키 추가 — 터미널에 아래 명령어를 입력하여 SSH 에이전트에 개인 키를 추가하고, 맥의 키체인에 저장하도록 합니다. 이렇게 하면 재부팅 후에도 키가 자동으로 로드됩니다.
ssh-add --apple-use-keychain ~/.ssh/id_ed25519* 이때 키 생성 시 설정했던 암호를 입력해야 합니다.
- SSH 설정 파일 생성/수정 —
~/.ssh/config파일을 열거나 생성하여 아래 내용을 추가합니다. 만약 파일이 없다면touch ~/.ssh/config명령으로 생성할 수 있습니다.Host github.com Hostname github.com User git IdentityFile ~/.ssh/id_ed25519 UseKeychain yes AddKeysToAgent yes - 연결 테스트 — 모든 설정이 올바르게 되었는지 확인하기 위해 깃허브에 SSH 연결 테스트를 수행합니다.
ssh -T git@github.com* 처음 연결 시 “Are you sure you want to continue connecting (yes/no)?” 메시지가 나타나면 ‘yes’를 입력합니다.
* 연결이 성공하면 “Hi [유저명]! You’ve successfully authenticated…” 메시지가 출력됩니다.
Photo by Markus Winkler on Pexels
문제 해결: 여전히 비밀번호를 묻는다면?
위의 단계를 모두 따랐음에도 불구하고 여전히 push 시 비밀번호를 입력해야 하거나 연결 오류가 발생할 수 있습니다. 이는 일반적으로 Git 원격 URL 설정, SSH 키 파일 권한, 또는 SSH 에이전트 문제 등 3가지 핵심 원인 중 하나로 인해 발생합니다. 하지만 걱정 마세요, 해결 방법은 비교적 간단합니다.
이 섹션에서는 가장 흔한 문제 상황들을 진단하고 해결하는 방법을 제시합니다. 이 팁들을 적용하면 대부분의 연결 문제를 해결하고 깃허브와 원활하게 소통할 수 있을 것입니다. 99%의 사용자가 이 방법들로 문제를 해결합니다.
아래 해결책을 시도하기 전에 터미널을 완전히 종료하고 다시 시작한 후 시도해 보는 것이 좋습니다. 일부 설정 변경은 터미널 세션 재시작 후에 적용될 수 있습니다.
- Git 원격(Remote) URL 확인 및 변경 — 프로젝트의 Git 원격 URL이 SSH 방식으로 설정되어 있는지 확인합니다. 만약 HTTPS 방식으로 되어 있다면 비밀번호를 요구할 수 있습니다.
git remote -v # 현재 원격 URL 확인 git remote set-url origin git@github.com:USERNAME/REPOSITORY.git # SSH 방식으로 변경 (USERNAME과 REPOSITORY는 실제 값으로 변경) - SSH 키 파일 권한 확인 — SSH 개인 키 파일의 권한이 너무 개방적으로 설정되어 있으면 SSH가 이를 사용하지 않을 수 있습니다. 개인 키는 소유자만 읽고 쓸 수 있어야 합니다.
chmod 600 ~/.ssh/id_ed25519 # 개인 키 권한 설정 chmod 700 ~/.ssh # .ssh 디렉토리 권한 설정 (선택 사항이지만 권장) - SSH 에이전트 재시작 또는 키 다시 추가 — SSH 에이전트가 정상적으로 작동하지 않거나 키를 제대로 로드하지 못하는 경우 발생합니다.
eval "$(ssh-agent -s)" # SSH 에이전트 시작 ssh-add --apple-use-keychain ~/.ssh/id_ed25519 # 키 다시 추가*
ssh-add -l명령으로 현재 에이전트에 등록된 키 목록을 확인할 수 있습니다.
맥에서 깃허브 SSH 키를 생성하고 연결하는 과정은 안전하고 효율적인 개발 환경을 위한 필수 단계입니다. Ed25519 키 생성부터 깃허브 등록, 그리고 SSH 에이전트 설정 및 config 파일 구성까지의 4단계 가이드를 통해 더 이상 push 시 비밀번호를 입력해야 하는 불편함을 겪지 않을 것입니다. 만약 문제가 발생하더라도, 원격 URL 확인, 파일 권한 조정, 에이전트 재설정이라는 3가지 핵심 문제 해결 방법을 통해 대부분의 상황을 해결할 수 있습니다.
지금 바로 적용해 보세요.
- Generating a new SSH key and adding it to the ssh-agent – GitHub Docs — 깃허브 공식 문서에서 SSH 키 생성 및 에이전트 추가 방법을 자세히 설명합니다.
- Adding a new SSH key to your GitHub account – GitHub Docs — 깃허브 계정에 SSH 키를 등록하는 공식 가이드입니다.
동영상으로 보는 맥 깃허브 SSH 키 생성 연결
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
자주 묻는 질문
Q. 깃허브에 연결할 때 HTTPS 대신 SSH를 사용하는 주된 이점은 무엇인가요?
A. SSH를 사용하면 매번 사용자 이름과 비밀번호(또는 개인 액세스 토큰)를 입력하지 않고도 안전하게 깃허브 리포지토리에 접근할 수 있습니다. 한 번 설정하면 SSH 키가 사용자 인증을 대신 처리하여 개발 워크플로우를 더 빠르고 편리하게 만들어줍니다. 특히 보안 측면에서도 강력한 암호화를 제공합니다.
Q. 이미 SSH 키가 있는데 새로 만들어야 하나요?
A. 아니요, 이미 SSH 키가 있다면 기존 키를 그대로 깃허브에 등록하여 사용할 수 있습니다. `ls -al ~/.ssh` 명령어로 키가 있는지 확인하고, `.pub` 확장자를 가진 공개 키의 내용을 깃허브 계정에 추가하면 됩니다. 여러 키를 관리할 필요 없이 하나의 키로 편리하게 작업할 수 있습니다.
Q. SSH 키 설정 후 깃허브 연결이 제대로 작동하는지 어떻게 확인할 수 있나요?
A. 설정이 완료된 후 `ssh -T git@github.com` 명령어를 터미널에 입력하여 연결 테스트를 할 수 있습니다. 이 명령어를 실행했을 때 ‘Hi [your-username]! You’ve successfully authenticated…’와 같은 메시지가 나타나면 연결이 성공적으로 이루어진 것입니다. 만약 오류 메시지가 뜬다면 설정 단계를 다시 확인해야 합니다.
Q. SSH 키 설정 과정 중 오류가 발생하거나 연결 테스트에 실패하면 어떻게 해야 하나요?
A. 먼저, 공개 키가 깃허브 계정에 올바르게 등록되었는지 확인하세요. 그 다음 `ssh-add` 명령어로 개인 키가 SSH 에이전트에 추가되었는지 확인하고, `eval “$(ssh-agent -s)”` 명령어를 사용하여 에이전트가 실행 중인지 확인해 볼 수 있습니다. 만약 여전히 문제가 발생한다면, 상세한 오류 메시지를 검색하거나 가이드의 문제 해결 섹션을 참고하여 해결책을 찾아보세요.
📚 함께 읽으면 좋은 글