깃허브에 파일 업로드할 때 자주 나는 인증 오류 대처법

깃허브 인증 오류를 마주하는 개발자들을 위하여

개발을 시작하고 깃허브에 첫 코드를 올리거나 평소처럼 파일을 업로드하려 할 때 빨간색 경고 문구와 함께 로그인이 거부되는 경험은 누구나 한 번쯤 겪는 당황스러운 순간입니다.

열심히 작성한 코드를 서버에 안전하게 저장하고 협업을 시작해야 하는데 문앞에서 가로막힌 기분이 들기 마련입니다. 특히 터미널 창에 낯선 영어 에러 메시지가 뜰 때는 어디서부터 손을 대야 할지 막막해집니다.

과거에는 아이디와 비밀번호만 입력하면 쉽게 파일을 올릴 수 있었지만 보안이 강화되면서 이제는 더 이상 예전의 방식대로 접근할 수 없게 되었습니다.

깃허브는 개발자의 소스 코드를 안전하게 보호하기 위해 인증 방식을 대폭 강화했으며 이 과정에서 많은 사용자가 사소한 설정 차이로 인해 오류를 마주하고 있습니다.

이번 글에서는 깃허브에 파일을 업로드할 때 가장 흔하게 발생하는 인증 오류의 원인을 파악하고 누구나 쉽게 따라 할 수 있는 실용적인 해결 방법을 상세히 알아보겠습니다.

비밀번호 입력의 시대가 저물고 토큰이 필요한 이유

많은 초보자들이 깃허브 터미널 창에 계정 비밀번호를 입력했다가 인증 거부 오류를 마주하곤 합니다. 하지만 이는 시스템이 고장 난 것이 아니라 깃허브의 보안 정책이 변경되었기 때문입니다.

과거에는 웹사이트에 로그인하는 비밀번호를 터미널에서도 그대로 사용할 수 있었지만 보안상의 취약점으로 인해 2021년 8월부터 계정 비밀번호를 이용한 원격 저장소 접근이 전면 차단되었습니다.

이제는 계정 비밀번호 대신 개인 접근 토큰이라는 일종의 임시 비밀번호를 발급받아 사용해야 합니다. 이 토큰은 특정 권한만 가질 수 있고 언제든지 폐기할 수 있기 때문에 훨씬 안전합니다.

비밀번호가 유출되더라도 계정 전체가 해킹당할 위험을 줄여주는 효과가 있습니다. 따라서 깃허브에 파일을 올릴 때 인증 오류가 난다면 가장 먼저 기존의 비밀번호 방식에서 벗어나 새로운 인증 수단을 사용하고 있는지 점검해야 합니다.

개인 접근 토큰을 발급받고 올바르게 사용하는 방법

인증 오류를 해결하는 가장 확실하고 기본적인 방법은 개인 접근 토큰을 생성하는 것입니다. 깃허브 웹사이트에 로그인한 후 우측 상단의 프로필 아이콘을 눌러 설정 메뉴로 이동합니다.

설정 페이지의 가장 하단에 위치한 개발자 설정 메뉴를 선택하고 개인 접근 토큰 항목으로 진입합니다. 그중에서 Tokens (classic) 메뉴를 선택하고 Generate new token (classic) 버튼을 눌러 새 토큰을 만들면 됩니다.

토큰을 생성할 때는 이 토큰을 어디에 사용할 것인지 용도를 적어 두는 것이 좋습니다. 그리고 중요한 부분은 권한 설정입니다. 코드를 올리고 내려받는 기본적인 작업에는 repo 항목에 체크해야 합니다. 생성 버튼을 누르면 화면에 긴 문자열 형태의 토큰이 나타나는데, 이 값은 페이지를 벗어나면 다시 확인할 수 없습니다. 그래서 비밀번호 관리자처럼 다른 사람이 볼 수 없는 안전한 곳에 바로 복사해 두어야 합니다. 토큰은 비밀번호와 같으므로 다른 사람에게 보여 주거나 블로그나 메신저에 올리면 안 됩니다.

이렇게 발급받은 토큰은 터미널에서 비밀번호를 물어볼 때 그대로 붙여넣으면 됩니다. 화면에는 입력하는 내용이 표시되지 않으므로 당황하지 말고 복사한 토큰을 마우스 우클릭이나 단축키로 붙여넣은 뒤 엔터를 누르면 정상적으로 인증이 완료됩니다.

운영체제별 자격 증명 관리자의 함정에서 벗어나기

토큰을 새로 발급받았음에도 불구하고 계속해서 인증 오류가 발생하는 경우가 있습니다. 이는 컴퓨터의 운영체제가 이전에 실패했던 잘못된 로그인 정보를 기억하고 있기 때문입니다.

윈도우나 맥과 같은 운영체제는 사용자의 편의를 위해 한번 입력한 아이디와 비밀번호를 저장해 두는 자격 증명 기능을 제공하는데 이로 인해 낡은 정보가 계속 충돌을 일으키는 것입니다.

윈도우 사용자의 경우 제어판에 있는 자격 증명 관리자에 들어가서 일반 자격 증명 목록을 확인해야 합니다. 그곳에 깃허브와 관련된 항목이 있다면 과감히 삭제하거나 수정하여 새로 발급받은 토큰 정보를 입력해야 합니다.

맥 사용자라면 시스템에 내장된 키체인 접근 앱을 실행한 뒤 깃허브를 검색하여 기존에 저장된 비밀번호 항목을 찾아 지워주어야 문제가 해결됩니다.

이 과정을 거치고 나면 다음 파일 업로드 시도 시 운영체제가 새로운 인증 정보를 요구하게 되며 그때 올바른 토큰을 입력하면 앞으로는 오류 없이 원활하게 코드를 관리할 수 있습니다.

원격 저장소 주소 설정 오류 바로잡기

인증 방식에는 문제가 없는데도 불구하고 권한이 없다는 에러가 발생한다면 원격 저장소의 주소가 잘못 지정되었을 가능성이 높습니다. 깃허브는 보안 접속 방식인 SSH 방식과 기존의 웹 주소 방식을 모두 지원하는데 이 두 가지 방식 중 현재 내 컴퓨터 환경에 맞지 않는 주소가 등록되어 있으면 인증에 실패하게 됩니다.

터미널에 명령어 창을 띄우고 현재 연결된 원격 저장소의 주소를 확인하는 명령어를 입력해 볼 수 있습니다. 주소가 올바르게 설정되어 있는지 눈으로 직접 확인하고 만약 주소가 잘못되었거나 HTTPS 방식 대신 SSH 방식을 써야 하는데 주소가 꼬여 있다면 이를 올바른 주소로 교체해 주어야 합니다.

• 현재 설정된 저장소 주소 확인하기: git remote -v
• 잘못된 주소 연결 끊기: git remote remove origin
• 올바른 HTTPS 혹은 SSH 주소로 바꾸기: git remote set-url origin 새주소

아래 화면은 연습용 폴더에서 이 명령어들을 직접 실행한 결과입니다. 처음에는 HTTPS 주소였던 origin이 set-url 명령어를 실행한 뒤 SSH 주소로 바뀐 것을 볼 수 있습니다.

주소를 재설정할 때는 깃허브 저장소 페이지에서 초록색 코드 버튼을 눌렀을 때 나오는 주소를 복사하여 사용하는 것이 가장 안전합니다. 사소한 오타 하나로 인해 인증이 거부될 수 있으므로 직접 타이핑하는 것보다 복사해서 붙여넣는 방식을 권장합니다.

SSH 키를 활용한 비밀번호 없는 편리한 업로드

매번 토큰을 발급받고 입력하는 과정이 번거롭게 느껴진다면 SSH 키를 등록하는 것이 좋은 대안입니다. 이 방식을 한 번 설정해 두면 그 이후에는 토큰이나 계정 비밀번호를 입력하지 않고도 파일을 올리고 내려받을 수 있어 작업이 편해집니다. 다만 키에 암호(패스프레이즈)를 설정했다면 그 암호는 입력해야 할 수 있습니다.

컴퓨터의 터미널에서 고유한 보안 키를 생성하는 명령어를 입력하면 본인만의 공개키와 비밀키가 만들어집니다. 생성된 공개키의 내용을 복사하여 깃허브 설정 페이지의 SSH 및 GPG 키 메뉴에 등록하면 준비가 끝납니다. 이 과정은 내 컴퓨터가 깃허브 서버와 신뢰 관계를 맺는 과정으로 등록 이후에는 별도의 인증 절차 없이 안전한 통신이 가능해집니다.

키를 만드는 명령어는 ssh-keygen -t ed25519 -C 이메일주소 입니다. 아래 화면은 저장 위치를 따로 정해 만든 연습용 키를 실행한 결과이고, 마지막 줄의 ssh-ed25519로 시작하는 한 줄이 깃허브에 등록하는 공개키입니다. 비밀키는 다른 사람에게 보여 주면 안 되니 공개키만 복사해서 사용하세요.

보안성이 매우 높으면서도 매번 로그인을 해야 하는 번거로움을 없애주기 때문에 많은 개발자가 사용하는 방식입니다. 처음 설정할 때 다소 복잡하게 느껴질 수 있지만 인터넷에 공개된 가이드를 따라 차근차근 진행하면 누구나 쉽게 자신의 컴퓨터를 등록할 수 있습니다.

깃허브 데스크톱 프로그램을 활용한 직관적인 해결

명령어 기반의 터미널 환경이 여전히 낯설고 복잡하게 느껴진다면 깃허브에서 공식적으로 제공하는 전용 데스크톱 프로그램을 사용하는 것이 현명한 선택입니다.

이 프로그램은 파일 업로드와 다운로드를 마우스 클릭 몇 번으로 처리할 수 있도록 시각적인 인터페이스를 제공하여 인증 오류를 원천적으로 줄여줍니다.

프로그램을 처음 실행할 때 웹브라우저를 통한 로그인 연동을 지원하기 때문에 복잡한 토큰을 직접 복사해서 붙여넣을 필요가 없습니다. 깃허브 웹사이트 계정 권한을 그대로 이어받아 작동하므로 인증 과정에서 발생하는 오류의 빈도가 현저히 낮아집니다.

또한 변경된 파일이 무엇인지 시각적으로 보여주기 때문에 실수로 잘못된 파일을 올리는 상황도 자연스럽게 방지할 수 있습니다.

초보자일수록 터미널의 에러 메시지에 스트레스를 받기보다는 이러한 친화적인 도구를 활용하여 개발 본연의 과정에 집중하는 것이 더 좋은 선택입니다.

흔히 오해하는 인증 관련 사실들

깃허브 인증 오류와 관련해서 많은 사람들이 오해하는 부분들이 존재합니다. 가장 대표적인 오해는 깃허브 웹사이트에 로그인할 때 쓰는 이메일 주소나 비밀번호를 터미널에서도 똑같이 쓸 수 있을 것이라는 생각입니다. 앞서 언급했듯 웹 로그인 비밀번호와 터미널 인증용 토큰은 완전히 별개의 체계로 움직입니다.

또 다른 오해는 한번 토큰을 만들면 평생 쓸 수 있다는 점입니다. 토큰은 만들 때 유효 기간을 30일, 90일처럼 정할 수 있고, 기간이 지나면 더 이상 쓸 수 없습니다. 만료 없는 토큰도 만들 수 있지만 유출되면 위험하므로 권장되지 않습니다.

시간이 지나 갑자기 인증 오류가 난다면 토큰의 유효 기간이 만료되었을 수 있으므로, 새로운 토큰을 발급받아 교체해 주면 해결됩니다.

이메일 주소 변경이나 계정 이름 변경 시에도 기존에 저장된 인증 정보와 충돌이 날 수 있으므로 계정에 큰 변화가 있었다면 자격 증명을 새로 갱신해 주는 습관을 들여야 합니다.

자주 묻는 질문과 실전 대처법

인증 오류를 해결하는 과정에서 개발자들이 공통적으로 궁금해하는 사항들을 모아보았습니다. 자신의 상황과 비교해 보면 해답을 찾기 수월해집니다.

• 질문: 토큰을 입력했는데도 계속 Authentication failed가 뜹니다. 왜 그럴까요?
• 답변: 자격 증명 관리자에 예전 정보가 남아있거나 토큰의 권한 범위가 잘못 지정되었을 가능성이 큽니다. repo 항목이 체크되어 있는지 확인하고 컴퓨터에 저장된 기존 인증 정보를 완전히 지운 뒤 다시 시도해 보세요.
• 질문: 토큰을 잃어버렸는데 다시 찾을 수 있나요?
• 답변: 분실한 토큰은 보안상 다시 조회할 수 없습니다. 설정 페이지에서 기존 토큰을 삭제하고 새로운 토큰을 다시 발급받아 사용하는 것이 유일한 방법입니다.
• 질문: 여러 개의 깃허브 계정을 하나의 컴퓨터에서 번갈아 가며 사용해도 되나요?
• 답변: 가능하지만 자격 증명이 꼬이기 쉽습니다. 계정마다 SSH 키를 달리 설정하거나 운영체제의 자격 증명 관리자를 통해 접근 정보를 철저히 관리해야 충돌을 막을 수 있습니다.

이처럼 깃허브 인증 오류는 대부분 보안 정책의 변화와 컴퓨터가 기억하고 있는 낡은 정보 사이의 불일치에서 발생합니다. 원인만 정확히 파악하고 올바른 대처법을 적용한다면 누구나 손쉽게 문제를 극복하고 원활하게 코드를 업로드할 수 있습니다.