개발자들과 코딩 입문자들에게 필수적인 버전 관리 시스템인 깃허브(GitHub). 그중에서도 터미널 명령어 대신 직관적인 그래픽 인터페이스(GUI)로 코드를 관리할 수 있게 해주는 ‘깃허브 데스크톱(GitHub Desktop)’은 많은 사용자에게 사랑받는 프로그램입니다.
하지만 코드를 수정하고 원격 저장소에 올리기 위해 ‘Push’ 버튼을 누르거나 코드를 내려받기 위해 ‘Pull’ 버튼을 눌렀을 때, 갑자기 “Authentication failed(인증 실패)”라는 오류 메시지가 뜨면서 작업이 전면 중단되는 경우가 있습니다. 급하게 코드를 커밋(Commit)하고 퇴근해야 하는 상황에서 이런 오류를 마주하면 눈앞이 캄캄해지기 마련입니다.
이러한 인증 오류는 프로그램 자체의 버그라기보다는 계정의 보안 설정 변경이나 윈도우(Windows) 운영체제에 임시로 저장된 로그인 정보가 꼬이면서 발생하는 아주 자연스러운 현상입니다. 오늘은 터미널이나 코딩에 익숙하지 않은 초보자분들도 클릭 몇 번으로 간단하게 이 문제를 해결할 수 있는 3단계 완벽 대처법을 아주 상세하게 정리해 드리겠습니다.
1. 깃허브 데스크톱 인증 오류(Authentication failed) 발생 원인
해결 방법을 적용하기 전에 이 문제가 왜 일어나는지 근본적인 원인을 파악하는 것이 중요합니다. 원인을 알고 나면 추후 비슷한 보안 관련 문제가 발생했을 때 당황하지 않고 스스로 대처할 수 있기 때문입니다.
- 비밀번호 변경 및 토큰 만료: 깃허브 웹사이트(GitHub.com)에서 계정 비밀번호를 최근에 변경했거나, 데스크톱 앱과 연동해 둔 개인 엑세스 토큰(Personal Access Token, PAT)의 유효기간이 만료된 경우입니다.
- 윈도우 자격 증명 관리자의 캐시 충돌: 윈도우는 사용자의 편의를 위해 로그인 정보를 ‘자격 증명 관리자’라는 곳에 보관합니다. 깃허브 웹사이트에서는 비밀번호가 바뀌었는데, 윈도우 내부에는 과거의 틀린 비밀번호가 그대로 남아있어 계속 잘못된 정보로 로그인을 시도하며 충돌하는 현상입니다.
- 2단계 인증(2FA) 활성화로 인한 접근 차단: 계정 보안 강화를 위해 깃허브에서 2단계 인증(Two-Factor Authentication)을 새롭게 켰을 경우, 기존의 단순 비밀번호 방식으로는 데스크톱 앱에서 접근할 수 없어 인증이 거부(Failed)됩니다.
원인을 파악하셨다면, 이제 아래의 1단계부터 3단계까지 차근차근 따라 해 보시기 바랍니다.
2. 깃허브 인증 오류 해결을 위한 3단계 실전 가이드
1단계: 윈도우 ‘자격 증명 관리자’에서 기존 깃허브 캐시 삭제
가장 흔한 원인인 윈도우 내부의 오래된 로그인 기록(캐시)을 깔끔하게 지워주는 첫 번째 단계입니다. 꼬여있는 실타래를 끊어내는 가장 중요한 작업입니다.
- 윈도우 바탕화면 좌측 하단의 돋보기(검색) 아이콘을 클릭한 후, 검색창에 ‘자격 증명 관리자’를 타이핑하여 제어판 앱을 실행합니다.
- 화면 상단에 보이는 두 가지 탭 중 우측의 [Windows 자격 증명]을 클릭합니다.
- ‘일반 자격 증명’ 목록을 스크롤 하여 아래로 내리다 보면
git:https://github.com또는GitHub - https://api.github.com이라는 이름으로 저장된 항목들을 찾을 수 있습니다. - 해당 깃허브 관련 항목의 우측 화살표(∨)를 눌러 상세 메뉴를 펼친 뒤 [제거] 버튼을 눌러 모조리 삭제해 줍니다.
- 자격 증명 창을 닫습니다. 이제 윈도우에 남아있던 잘못된 과거의 비밀번호가 완전히 초기화되었습니다.
2단계: 깃허브 데스크톱 앱 내 계정 로그아웃 및 재로그인
오래된 기록을 지웠으니, 이제 데스크톱 앱에서 깃허브 서버와 새롭게 통신(OAuth)을 연결해 줄 차례입니다.
- 깃허브 데스크톱(GitHub Desktop) 프로그램을 실행합니다.
- 프로그램 좌측 상단의 [File] 메뉴를 클릭한 뒤 [Options(옵션)]로 들어갑니다. (맥(Mac) 사용자의 경우 상단 메뉴바의 [GitHub Desktop] -> [Preferences]로 들어갑니다.)
- 옵션 창 좌측 메뉴에서 [Accounts] 탭을 클릭합니다.
- GitHub.com 항목 옆에 있는 [Sign out(로그아웃)] 버튼을 눌러 기존 계정 연결을 완전히 끊어줍니다.
- 로그아웃이 완료되면 다시 [Sign in(로그인)] 버튼을 누릅니다. 그러면 인터넷 브라우저 창이 열리면서 깃허브 웹사이트로 연결됩니다.
- 브라우저에서 깃허브 최신 계정 정보(변경된 비밀번호 또는 2FA 인증)로 로그인을 완료하고, 데스크톱 앱으로 리디렉션(돌아가기)을 허용해 줍니다.
대부분의 일반적인 인증 오류는 이 2단계까지만 진행하고 나면 깔끔하게 해결되며, 다시 정상적으로 Push와 Pull이 작동하게 됩니다.
3단계: Personal Access Token (PAT) 발급 및 수동 연동 (필요시)
만약 2단계의 브라우저 연동 방식이 보안 정책 등으로 인해 막혀있거나 계속해서 오류가 난다면, 깃허브의 ‘개인 엑세스 토큰(PAT)’을 발급받아 비밀번호 대신 입력하는 수동 연동 방식을 사용해야 합니다.
- 인터넷 브라우저를 열고 GitHub.com에 로그인한 뒤, 우측 상단의 본인 프로필 아이콘을 누르고 [Settings(설정)]로 들어갑니다.
- 좌측 메뉴 스크롤을 맨 아래로 내려 [Developer settings]를 클릭합니다.
- 좌측 메뉴에서 [Personal access tokens] -> [Tokens (classic)]을 차례대로 선택합니다.
- 우측 상단의 [Generate new token] 버튼을 누릅니다. 용도(Note)에 ‘GitHub Desktop’이라고 적고, Expiration(만료일)을 설정한 뒤, 하단의 권한 설정에서
repo(저장소 접근 권한) 항목에 반드시 체크를 해줍니다. - 페이지 하단의 녹색 버튼을 눌러 토큰을 생성하면,
ghp_로 시작하는 긴 영문/숫자 조합의 토큰 코드가 나타납니다. (이 코드는 지금 한 번만 보여지므로 반드시 복사해 둡니다.) - 다시 깃허브 데스크톱 앱으로 돌아와서 로그인을 시도할 때, 브라우저 로그인이 아닌 수동 로그인(Username and Password) 방식을 선택합니다.
- 아이디 란에는 본인의 깃허브 Username을 적고, 비밀번호 란에는 방금 복사한 토큰(PAT) 코드를 붙여넣기 한 뒤 [Sign in]을 누르면 완벽하게 인증이 통과됩니다.
3. 요약 및 깃허브 보안 관리 추가 팁 (마무리 주의사항)
위의 3단계 가이드를 천천히 잘 따라오셨다면, 여러분의 개발 흐름을 끊어먹던 깃허브 데스크톱의 ‘Authentication failed’ 인증 오류가 속 시원하게 해결되었을 것입니다. 핵심은 윈도우에 남은 잘못된 과거의 로그인 캐시를 지우고, 브라우저를 통한 재인증이나 토큰(PAT)을 활용하여 권한을 새롭게 갱신하는 것입니다.
마지막으로 보안과 관련된 중요한 주의사항을 덧붙입니다. 3단계에서 발급받은 Personal Access Token(PAT)은 여러분의 깃허브 계정 비밀번호와 완벽하게 동일한 강력한 권한을 가집니다. 따라서 이 토큰 코드를 타인에게 공유하거나, 본인이 작성 중인 퍼블릭(Public) 코드 소스 안에 적어둔 채로 깃허브에 업로드(Push)하는 실수를 절대 하셔서는 안 됩니다. 만약 토큰이 유출되었다고 의심된다면, 즉시 깃허브 웹사이트 설정(Developer settings)에 들어가 해당 토큰을 삭제(Revoke)하여 보안 사고를 예방하시기 바랍니다.
오늘 알려드린 트러블슈팅 가이드를 통해 오류 스트레스 없이 쾌적한 환경에서 즐겁게 코딩하시기를 응원합니다! 감사합니다.
답글 남기기