GitHub 인증 오류 해결: 비밀번호 대신 CLI·Credential Manager·SSH 사용하기

2023년 git pull을 실행했을 때 다음 오류를 만났다.

remote: Support for password authentication was removed on August 13, 2021.
fatal: Authentication failed for '...'

당시 기록에는 개인 액세스 토큰을 만든 뒤 git config --global user.password에 넣어 해결했다고 적었다. 토큰을 만든 방향은 맞았지만, user.password는 Git이 인증 정보를 관리하는 표준 설정이 아니다. 토큰을 전역 Git 설정에 평문으로 남길 위험도 있다.

지금 다시 정리하면 해결 순서는 단순하다. 먼저 원격 저장소가 HTTPS인지 SSH인지 확인하고, HTTPS라면 GitHub CLI 또는 Git Credential Manager를 우선 사용한다. 토큰을 직접 다뤄야 한다면 최소 권한과 만료 기간을 설정하고 운영체제의 안전한 저장소에 맡긴다.

먼저 원격 주소와 현재 인증 방식을 확인한다

git remote -v

주소가 https://github.com/OWNER/REPO.git이면 HTTPS 인증을 사용한다. git@github.com:OWNER/REPO.git이면 SSH 인증이다. 두 방식을 섞어 해결하려고 하면 토큰을 새로 만들어도 같은 오류가 반복될 수 있다.

GitHub CLI를 이미 사용 중이라면 로그인 상태도 확인한다.

gh auth status

인증 오류가 항상 비밀번호 정책 때문인 것은 아니다. 저장소 URL의 소유자와 이름이 맞는지, 현재 계정에 저장소 권한이 있는지, 조직에서 SAML SSO나 토큰 정책을 적용하는지도 함께 확인해야 한다.

HTTPS에서는 GitHub CLI가 가장 간단하다

GitHub 문서는 HTTPS 자격 증명을 기억하는 방법으로 GitHub CLI 또는 Git Credential Manager를 권장한다. CLI를 쓴다면 다음 명령으로 로그인한다.

gh auth login

질문이 나오면 GitHub.com과 HTTPS를 선택하고, Git 작업에도 자격 증명을 사용하도록 허용한다. 브라우저 인증을 마치면 다시 원격 접근을 확인한다.

git fetch

git fetch가 성공했다고 해서 바로 git pull을 실행해야 하는 것은 아니다. 먼저 원격 참조를 가져오는 단계와 로컬 브랜치에 병합하는 단계를 분리하면 인증 문제와 브랜치 충돌을 구분하기 쉽다.

GitHub CLI를 쓰지 않는 환경이라면 Git Credential Manager가 대안이다. macOS에서는 로그인 후 자격 증명을 키체인에 저장할 수 있고, Windows에서는 자격 증명 관리자와 연동된다. 구체적인 설치 방식은 운영체제와 Git 배포판에 따라 달라지므로 공식 문서를 확인하는 편이 안전하다.

토큰을 직접 사용할 때 지킬 기준

개인 액세스 토큰(PAT)은 HTTPS Git 작업에서 비밀번호 자리에 입력할 수 있다. 가능하면 fine-grained token을 사용하고 다음 범위만 부여한다.

• 접근해야 하는 리소스 소유자와 저장소만 선택한다.
• 필요한 작업이 읽기라면 Contents: read, 푸시가 필요하다면 필요한 쓰기 권한만 준다.
• 만료일을 설정한다.
• 조직 승인이 필요한 토큰인지 확인한다.
• 토큰을 원격 URL, 셸 스크립트, 블로그, Git 설정에 직접 넣지 않는다.

https://TOKEN@github.com/OWNER/REPO.git   # 사용하지 않는다

토큰이 터미널 기록이나 공개된 파일에 노출됐다면 파일에서 지우는 것만으로 끝나지 않는다. GitHub에서 해당 토큰을 폐기하고 새 토큰을 발급해야 한다.

예전에 넣은 user.password 설정은 제거한다

설정의 존재 여부를 값 노출 없이 확인할 수 있다.

if git config --global --get-regexp '^user\.password$' >/dev/null; then
  echo "legacy user.password entry exists"
fi

해당 설정에 토큰을 넣었던 것이 확실하다면 GitHub에서 토큰을 먼저 폐기한 뒤 항목을 제거한다.

git config --global --unset-all user.password

Git의 자격 증명 체계는 credential.helper와 운영체제 키체인 같은 credential helper를 사용한다. user.name과 user.email은 커밋 작성자 정보이고, 원격 저장소 로그인 정보가 아니다.

현재 연결된 helper는 다음처럼 확인할 수 있다.

git config --show-origin --get-all credential.helper

SSH로 전환하는 방법도 있다

장기간 같은 개발 장비에서 작업한다면 SSH 키를 등록하고 원격 주소를 바꿀 수 있다.

git remote set-url origin git@github.com:OWNER/REPO.git
ssh -T git@github.com

SSH 키 생성, ssh-agent 등록, GitHub 계정에 공개 키 추가가 먼저 끝나 있어야 한다. 회사 장비나 조직 저장소에서는 허용된 키 유형과 보안 정책도 확인한다.

다시 오류가 나면 이 순서로 좁힌다

1. git remote -v로 HTTPS와 SSH 중 어느 방식인지 본다.
2. 현재 로그인한 GitHub 계정에 저장소 권한이 있는지 확인한다.
3. HTTPS라면 gh auth status 또는 credential helper 상태를 확인한다.
4. 만료·폐기·조직 승인·SSO 제한이 있는 토큰인지 확인한다.
5. SSH라면 ssh -T git@github.com으로 GitHub까지의 인증만 따로 시험한다.
6. 인증이 통과한 뒤 브랜치 충돌이나 보호 규칙 문제를 별도로 본다.

이 글은 2023년에 실제로 만난 오류와 당시 해결 기록을 현재 공식 문서에 맞게 바로잡은 것이다. 지금 환경에서 같은 저장소의 로그인을 다시 재현한 결과는 아니므로, 마지막 성공 여부는 자신의 저장소에서 git fetch로 확인해야 한다.

참고 자료

• GitHub Docs: Git 자격 증명 캐싱
• GitHub Docs: 개인 액세스 토큰 관리
• GitHub Docs: SSH로 GitHub 연결
• Git 공식 문서: gitcredentials