[ssh] GitLab SSH 키 설정 및 문제 해결 시행착오 (MacBook)

GitLab SSH 키 설정 및 문제 해결 가이드 (MacBook)

GitLab에서 SSH로 원격 저장소에 접근하기 위해 SSH 키를 생성하고 설정하는 과정을 상세히 정리했습니다. 시행착오까지 포함하여 바로 사용할 수 있도록 정리하였으니, 복사해서 사용하세요.

---

✅ 1. SSH 키가 이미 있는지 확인하기

ls -al ~/.ssh

• 결과에 id_rsa와 id_rsa.pub 파일이 있다면, 이미 SSH 키가 생성되어 있는 상태입니다.
• 만약 .ssh 폴더가 없다면, 새로 생성하세요.

---

✅ 2. SSH 키 새로 생성하기

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

• -t rsa: RSA 방식으로 생성.
• -b 4096: 4096비트 길이로 생성 (더 안전).
• -C: 이메일 주석 (GitLab에 등록된 이메일로 입력).

입력 단계에서 주의사항

• 저장 경로: 기본 경로인 ~/.ssh/id_rsa로 두고 Enter.
• 패스프레이즈: 보안을 위해 입력해도 되고, 그냥 Enter로 넘어가도 됩니다.

---

✅ 3. SSH 공개 키 복사하기

공개 키 파일 내용을 복사해야 GitLab에 등록할 수 있습니다.

cat ~/.ssh/id_rsa.pub

• 출력된 내용을 전체 복사하세요.
• macOS에서는 아래 명령어로 자동 복사가 가능합니다.

pbcopy < ~/.ssh/id_rsa.pub

---

✅ 4. GitLab에 SSH 키 등록하기

1. GitLab에 로그인.
2. 우측 상단 프로필 아이콘 > Preferences로 이동.
3. 좌측 메뉴에서 SSH Keys 선택.
4. Key 입력란에 복사한 공개 키(id_rsa.pub의 내용)를 붙여넣기.
5. Title에는 키를 구분할 수 있는 이름 작성 (예: MacBook Pro).
6. Expiration date는 선택 사항.
7. Add key 버튼 클릭.

---

✅ 5. SSH 연결 테스트하기

ssh -T git@gitlab.com

• 처음 연결 시 다음과 같은 메시지가 뜨면:

The authenticity of host 'gitlab.com (xxx.xxx.xxx.xxx)' can't be established.
Are you sure you want to continue connecting (yes/no)?

• yes를 입력하세요.
• 성공적으로 연결되면 아래와 같은 메시지가 나옵니다.

Welcome to GitLab, @your_username!

---

⚠️ SSH 연결 실패 시 해결 방법

1. SSH 에이전트 시작하기

eval "$(ssh-agent -s)"

1. SSH 키를 에이전트에 추가하기

ssh-add ~/.ssh/id_rsa

1. 다시 SSH 연결 테스트

ssh -T git@gitlab.com

여전히 문제가 발생한다면:

• SSH 키 경로가 정확한지 확인 (ls ~/.ssh)
• GitLab에 등록된 키가 올바른지 다시 확인

---

✅ 추가로 확인할 사항

• Git Remote URL 확인

git remote -v

• SSH 주소로 되어 있어야 합니다. 만약 HTTPS로 되어 있다면 아래와 같이 변경하세요.

git remote set-url origin git@gitlab.com:username/repository.git

• SSH 키 삭제 후 재등록

문제가 계속될 경우, GitLab의 SSH Keys에서 기존 키를 삭제하고 다시 등록해보세요.

---

이 문서대로 진행하면 MacBook에서 GitLab SSH 설정을 완료할 수 있습니다. 그래도 문제가 있다면 네트워크 설정이나 권한 문제를 점검해 보세요.