맥 SSH 키 생성, 깃허브 연결 오류 없이 한번에

새로운 프로젝트를 시작하며 맥에서 깃허브에 SSH로 연결하려는데, 키 생성부터 등록까지 막히는 경험을 하셨다면 잘 찾아오셨습니다. 복잡한 과정 때문에 좌절감을 느끼기 쉽지만, 몇 가지 핵심 원리를 이해하고 단계별로 따라 하면 오류 없이 깔끔하게 연결할 수 있습니다.

함께 보면 좋은 글: 맥 API 키 환경변수 설정, 실수 없이 끝내기

이 문제는 SSH 키의 작동 방식과 깃허브 계정 설정 간의 차이 때문에 발생하는 경우가 대부분입니다. 이 글에서는 맥에서 SSH 키를 생성하고 깃허브에 안전하게 연결하는 모든 과정을 상세하게 설명하여, 여러분의 개발 환경 설정을 한 번에 끝낼 수 있도록 돕겠습니다.

SSH 키의 기본 원리 이해하기

SSH(Secure Shell) 키는 공개 키 암호화 방식을 사용하여 사용자 인증을 수행하는 메커니즘입니다. 복잡하게 들릴 수 있지만, 핵심은 '열쇠 한 쌍'으로 생각하면 이해하기 쉽습니다. 하나는 '개인 키'로, 절대 외부에 노출되어서는 안 되는 비밀 열쇠입니다. 다른 하나는 '공개 키'로, 이 열쇠로 잠긴 문은 개인 키로만 열 수 있다는 것을 증명하는 역할을 합니다. 깃허브에서는 이 공개 키를 여러분의 계정에 등록해두면, 맥에서 생성된 해당 개인 키로 접속할 때마다 여러분이 본인임을 증명할 수 있게 됩니다.

이러한 공개 키 암호화 방식은 비밀번호를 직접 주고받는 것보다 훨씬 안전합니다. 비밀번호는 중간에 탈취될 위험이 있지만, SSH 키는 공개 키와 개인 키가 분리되어 있어 통신 과정에서 개인 키가 노출될 위험이 극히 낮습니다. 깃허브는 이 공개 키를 사용하여 여러분의 맥이 보내는 접속 요청을 검증하고, 일치하는 경우에만 접근을 허용합니다. 따라서 SSH 키를 올바르게 생성하고 등록하는 것이 안전한 깃허브 연결의 첫걸음입니다.

실제로 많은 개발자들이 이 방식을 사용하여 비밀번호 입력 없이 빠르고 안전하게 코드 저장소에 접근합니다. 예를 들어, Apple 지원 문서(support.apple.com)에서도 SSH 키 사용을 권장하며, 이는 보안 강화와 함께 개발 생산성을 높이는 데 기여합니다. SSH 키를 사용하면 2단계 인증(2FA) 설정 시에도 비밀번호 대신 키를 사용하게 되어, 더욱 강력한 보안 환경을 구축할 수 있습니다.

Photo by ClickerHappy on Pexels

맥에서 SSH 키 생성 및 관리하기

맥에서 SSH 키를 생성하는 과정은 매우 간단합니다. 터미널을 열고 몇 가지 명령어를 입력하는 것으로 모든 것이 완료됩니다. 가장 일반적인 방법은 `ssh-keygen` 명령어를 사용하는 것입니다. 이 명령어는 공개 키와 개인 키로 구성된 한 쌍의 키 파일을 생성합니다. 기본적으로 이 키 파일들은 사용자의 홈 디렉토리 아래 `.ssh` 폴더에 저장됩니다. 예를 들어, `id_rsa`가 개인 키, `id_rsa.pub`이 공개 키가 됩니다. 이 중 `.pub` 확장자가 붙은 파일이 깃허브에 등록할 공개 키입니다.

명령어를 실행하면 키 파일 저장 위치와 비밀번호(passphrase) 설정을 묻습니다. 특별한 이유가 없다면 기본 저장 위치를 그대로 사용하고, 비밀번호는 비워두거나 강력한 비밀번호를 설정할 수 있습니다. 비밀번호를 설정하면 개인 키를 사용할 때마다 해당 비밀번호를 입력해야 하므로, 자동화된 스크립트 등에서는 보통 비밀번호 없이 사용하는 경우가 많습니다. 하지만 보안을 최우선으로 한다면 반드시 강력한 비밀번호를 설정하는 것이 좋습니다. 비밀번호를 설정하지 않으면, 마치 비밀번호 없이 로그인하는 것처럼 바로 접근할 수 있게 됩니다. 이 점은 편리하지만 보안 위험을 증가시킬 수 있으니 신중하게 결정해야 합니다.

간혹 이전 명령어를 불러와 사용하는 개발자들도 있습니다. "$ ssh-keygen 해서 .ssh ... 방법이긴한데.. 저같은 경우는, 터미널 키자 마자 방향키를 위로 올려보면 이전 커맨드를 불러오면서 나오는 ssh 명령어를 불러 씁니다...." (출처: clien.net) 이처럼 자주 사용하는 명령어는 터미널 히스토리를 활용하면 편리하게 재사용할 수 있습니다. 기본적으로 `ssh-keygen` 명령어는 다음과 같이 실행합니다.

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

위 명령어에서 `-t rsa`는 키 타입을 RSA로 지정하고, `-b 4096`은 키의 길이를 4096비트로 설정하여 보안 강도를 높입니다. `-C` 옵션은 키에 대한 설명을 추가하는 것으로, 보통 이메일 주소를 사용합니다. 이렇게 생성된 키는 `~/.ssh/id_rsa` (개인 키)와 `~/.ssh/id_rsa.pub` (공개 키) 형태로 저장됩니다. 만약 이미 키가 존재한다는 메시지가 나온다면, 기존 키를 덮어쓸 것인지 아니면 새로운 이름으로 저장할 것인지 선택해야 합니다. 실수로 기존 키를 덮어쓰지 않도록 주의해야 합니다. 예를 들어, `~/.ssh/github_rsa` 와 같이 다른 이름으로 저장할 수도 있습니다.

깃허브 계정에 SSH 키 등록하기

SSH 키를 생성했다면, 이제 이 공개 키를 깃허브 계정에 등록해야 합니다. 깃허브 웹사이트에 접속하여 여러분의 계정 설정으로 이동합니다. 왼쪽 사이드바에서 'SSH and GPG keys' 메뉴를 찾을 수 있습니다. 여기에 'New SSH key' 또는 'Add SSH key' 버튼을 클릭하여 새로운 키를 등록합니다. 키 등록 페이지에서는 'Title'과 'Key' 두 가지 필드를 입력해야 합니다.

Title 필드에는 이 키가 어떤 맥에서 생성되었는지 쉽게 알아볼 수 있도록 이름을 붙여줍니다. 예를 들어, 'My MacBook Pro' 또는 'Work Laptop'과 같이 명확하게 작성하는 것이 좋습니다. Key 필드에는 앞에서 생성한 공개 키의 내용을 그대로 복사하여 붙여넣어야 합니다. 공개 키 파일(`~/.ssh/id_rsa.pub`)의 내용을 복사할 때는 텍스트 편집기나 터미널 명령어를 사용할 수 있습니다. 터미널에서 `cat ~/.ssh/id_rsa.pub` 명령어를 사용하여 내용을 확인하고 복사하는 것이 가장 정확합니다. 복사할 때 줄바꿈이나 공백이 잘못 포함되지 않도록 전체 내용을 빠짐없이 복사하는 것이 중요합니다. 깃허브는 이 키를 사용하여 여러분의 접속을 인증하므로, 단 한 글자라도 틀리면 연결에 실패하게 됩니다.

실제 사용자는 "네 맞습니다. 단순하게 표현하자면 sshpass는 키 등록 작업을 도와주는 역할이에요. (직접 등록보다 덜 귀찮아요) 요약하자면 키 생성 -> sshpass로 키 등록 이렇게 됩니다. 생각해보니 보안 부분은 삭제해도 될 내용이네요." (출처: clien.net) 라고 말합니다. `sshpass`는 비밀번호를 직접 입력하지 않고 스크립트 등에서 SSH 접속을 자동화할 때 유용하지만, SSH 키를 사용하는 경우 `ssh-copy-id` 와 같은 명령어를 사용하여 키를 원격 서버에 복사하는 것이 일반적입니다. 깃허브의 경우 웹 인터페이스를 통해 공개 키를 직접 등록하므로 `sshpass`나 `ssh-copy-id`가 필요하지 않습니다.

키 등록 후에는 'Add SSH key' 버튼을 클릭하여 최종적으로 저장합니다. 깃허브는 여러분이 등록한 공개 키와 맥에서 생성된 개인 키를 비교하여 인증을 수행합니다. 만약 이전에 `ssh-keygen` 실행 시 비밀번호를 설정했다면, 깃허브 계정 설정과는 별개로 개인 키를 사용할 때마다 해당 비밀번호를 입력해야 합니다. 이 비밀번호는 깃허브 계정 비밀번호와는 전혀 다른 것입니다.

SSH 연결 테스트 및 일반적인 오류 해결하기

SSH 키를 깃허브에 등록한 후에는 연결이 제대로 작동하는지 테스트하는 것이 중요합니다. 터미널에서 다음 명령어를 입력하여 깃허브와의 SSH 연결을 확인할 수 있습니다.

ssh -T git@github.com

이 명령어를 실행했을 때, "Hi [Your Username]! You've successfully authenticated, but GitHub does not provide shell access." 와 같은 메시지가 나타나면 SSH 연결이 성공적으로 설정된 것입니다. 만약 처음 연결하는 경우, "Are you sure you want to continue connecting (yes/no/[fingerprint])?" 라는 질문이 나올 수 있습니다. 이때 'yes'를 입력하면 해당 호스트의 키를 저장하게 됩니다. 이는 보안상의 이유로, 연결하려는 서버가 진짜 깃허브 서버인지 확인하는 과정입니다. 이 과정에서 깃허브의 호스트 키 지문(fingerprint)을 확인하는 것이 좋습니다. 깃허브 공식 문서에서 최신 호스트 키 지문을 확인할 수 있습니다.

만약 연결 테스트 시 오류가 발생한다면, 몇 가지 일반적인 원인을 점검해볼 수 있습니다. 첫째, 깃허브에 등록한 공개 키와 맥에 저장된 공개 키 내용이 일치하는지 다시 한번 확인해야 합니다. 공개 키 파일(`~/.ssh/id_rsa.pub`)을 열어 깃허브 설정에 등록된 키와 한 글자도 빠짐없이 같은지 비교해보세요. 둘째, 개인 키 파일(`~/.ssh/id_rsa`)의 권한 설정이 올바른지 확인해야 합니다. SSH는 보안을 위해 개인 키 파일에 대한 접근 권한을 엄격하게 제한합니다. 터미널에서 `chmod 600 ~/.ssh/id_rsa` 명령어를 사용하여 개인 키 파일의 권한을 소유자만 읽고 쓸 수 있도록 설정하는 것이 일반적입니다. 현재 macOS의 기본 권한 설정이 엄격하여 이 부분이 문제가 되는 경우가 종종 있습니다.

셋째, SSH 에이전트가 제대로 실행되고 있는지 확인해야 합니다. `ssh-add -l` 명령어를 사용하여 현재 SSH 에이전트에 등록된 키 목록을 확인할 수 있습니다. 만약 키가 등록되어 있지 않다면, `ssh-add ~/.ssh/id_rsa` 명령어를 사용하여 개인 키를 SSH 에이전트에 추가해야 합니다. 비밀번호를 설정한 경우, 이 과정에서 비밀번호를 입력해야 합니다. 넷째, `.ssh/config` 파일에 잘못된 설정이 있는지 점검할 수 있습니다. 예를 들어, 여러 개의 SSH 키를 사용하는 경우, 각 호스트별로 어떤 키를 사용할지 명시해야 할 수 있습니다. 기본적으로 깃허브와 연결할 때는 `git@github.com` 주소를 사용하며, 특별한 설정이 없다면 `~/.ssh/id_rsa` 키를 자동으로 사용합니다. 이처럼 다양한 원인이 있을 수 있으므로, 오류 메시지를 주의 깊게 읽고 해당 메시지에 맞는 해결책을 찾아 적용하는 것이 중요합니다. 예를 들어, "Permission denied (publickey)" 오류는 주로 키가 올바르게 등록되지 않았거나 권한 설정에 문제가 있을 때 발생합니다.

SSH 키 활용의 확장성과 보안 고려사항

맥에서 생성한 SSH 키는 깃허브뿐만 아니라 GitLab, Bitbucket 등 다양한 Git 호스팅 서비스에서 사용할 수 있습니다. 각 서비스마다 SSH 키를 등록하는 방법은 조금씩 다르지만, 기본 원리는 동일합니다. 해당 서비스의 계정 설정에서 공개 키를 등록하고, 맥에서는 해당 서비스의 Git 저장소를 SSH 프로토콜(`git@service.com:username/repo.git`)을 사용하여 클론하거나 푸시하면 됩니다.

더 나아가, SSH 키는 Git뿐만 아니라 SCP(Secure Copy)나 SFTP(SSH File Transfer Protocol)와 같은 파일 전송 프로토콜에서도 인증 수단으로 활용될 수 있습니다. 이를 통해 원격 서버에 안전하게 파일을 복사하거나 접근할 수 있습니다. 예를 들어, 웹 서버에 파일을 업로드하거나 데이터베이스 백업 파일을 가져오는 등의 작업에 SSH 키를 사용할 수 있습니다. 이는 비밀번호 기반 인증보다 훨씬 안전하고 편리한 방법입니다. Apple의 공식 문서에서도 SSH 키를 사용하여 원격 서버에 안전하게 접근하는 방법을 설명하고 있으며, 이는 개발자들에게 필수적인 기술 중 하나로 자리 잡았습니다.

보안 측면에서는 SSH 키를 주기적으로 관리하는 것이 중요합니다. 사용하지 않는 키는 삭제하고, 개인 키에 강력한 비밀번호를 설정하며, 최신 버전의 SSH 프로토콜을 유지하는 것이 좋습니다. 또한, 여러 사람이 하나의 계정을 공유하여 사용하는 경우, 각 사용자별로 고유한 SSH 키를 발급하고 관리하는 것이 보안 감사 및 책임 추적에 용이합니다. 예를 들어, 한 팀원이 퇴사했을 때 해당 사용자의 SSH 키만 비활성화하면 보안을 유지할 수 있습니다. M3 칩셋과 같이 최신 맥 하드웨어는 보안 기능이 강화되어 있어, 이러한 보안 설정을 더욱 효과적으로 관리할 수 있는 기반을 제공합니다. 최신 macOS 버전(예: macOS 15.2)에서는 보안 기능이 지속적으로 업데이트되므로, 항상 최신 상태를 유지하는 것이 좋습니다.

다양한 SSH 키 관리 도구들도 존재하지만, 기본적인 `ssh-keygen` 명령어와 `.ssh` 디렉토리 관리를 잘 이해하는 것만으로도 대부분의 상황에 대처할 수 있습니다. 만약 여러 프로젝트에서 다양한 키를 사용해야 한다면, `.ssh/config` 파일을 잘 활용하여 각 호스트별로 사용할 키를 지정하는 것이 효율적입니다. 예를 들어, 다음과 같이 설정하여 특정 호스트에는 특정 키를 사용하도록 지정할 수 있습니다.

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/github_rsa
  IdentitiesOnly yes

Host gitlab.com
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/gitlab_rsa
  IdentitiesOnly yes

이 설정은 `github.com`으로 접속할 때는 `~/.ssh/github_rsa` 키를, `gitlab.com`으로 접속할 때는 `~/.ssh/gitlab_rsa` 키를 사용하도록 명시합니다. `IdentitiesOnly yes` 옵션은 지정된 키만 사용하도록 강제하여, 실수로 다른 키가 사용되는 것을 방지합니다. 이러한 설정은 복잡한 개발 환경에서 보안과 편의성을 동시에 확보하는 데 큰 도움이 됩니다.