GitHub 토큰과 Git 인증: personal access token, Git Credential Manager, 비밀번호 없이 push

GitHub 비밀번호를 Git에서 쓸 수 없는 이유

git push를 할 때 GitHub 아이디와 비밀번호를 입력했는데 거부된다면, 오타 때문이 아닙니다. 2021년 8월 13일부터 GitHub는 HTTPS로 하는 Git 작업에서 비밀번호 인증을 중단했습니다. 대신 GitHub 토큰(personal access token, PAT)을 쓰거나, Git Credential Manager가 브라우저에서 처리하는 인증을 써야 합니다.

오류 메시지는 다음과 같습니다.

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/... for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/user/project.git/'

이유는 간단합니다. 계정 비밀번호는 모든 기능에 접근할 수 있고, 하나의 저장소로 범위를 제한할 수 없으며, 취소하기도 번거롭습니다. 반면 토큰은 특정 작업을 위해 만들어지고, 유효 기간과 권한 집합을 가지며, 유출되더라도 비밀번호를 바꾸지 않고 몇 분 안에 삭제할 수 있습니다. GitLab과 Bitbucket도 같은 방향으로 가고 있어서, 아래 내용은 그 서비스들에도 기본적으로 적용됩니다.

인증 방식 두 가지: HTTPS와 SSH

Git은 원격 저장소와 두 가지 프로토콜 중 하나로 통신합니다. 어떤 프로토콜을 쓰느냐에 따라 로그인 방식이 달라집니다.

SSH 키는 한 번만 설정하면, 그다음부터 Git이 아이디도 비밀번호도 묻지 않습니다. 키를 만들고 GitHub에 등록하는 방법은 Git 설정 관련 글에서 자세히 다뤘으므로, 여기서는 초보자가 비밀번호 입력 요청을 가장 자주 만나는 HTTPS에 집중하겠습니다. 저장소가 어떤 프로토콜을 쓰는지는 다음 명령으로 확인할 수 있습니다.

git remote -v
origin  https://github.com/user/project.git (fetch)
origin  https://github.com/user/project.git (push)

GitHub 토큰(personal access token) 만들기

personal access token은 비밀번호 대신 프로그램이 GitHub에 접근할 때 쓰도록 발급되는, 길고 무작위한 문자열입니다. classic 토큰은 ghp_로 시작하고, fine-grained 토큰은 github_pat_로 시작합니다. 토큰은 만든 직후 한 번만 보여 주므로, 바로 비밀번호 관리자에 복사해 두세요.

단계별 방법

1. github.com에 로그인하고, 오른쪽 위의 프로필 사진을 눌러 Settings를 엽니다.
2. 왼쪽 메뉴 맨 아래의 Developer settings, 그다음 Personal access tokens를 선택합니다.
3. 종류를 고릅니다. Fine-grained tokens(권장) 또는 Tokens (classic)이며, 새 토큰을 만드는 버튼을 누릅니다.
4. 알아보기 쉬운 이름(예: "노트북, 회사용"), 만료 기간, 권한을 설정합니다.
5. 생성 버튼을 누르고 토큰을 바로 복사합니다.

Fine-grained와 classic의 차이

Fine-grained 토큰은 특정 저장소와 세부 권한으로 범위를 제한할 수 있습니다. 일반적인 코드 작업에는 필요한 저장소를 고르고, 저장소 권한에서 Contents: Read and write를 설정하면 됩니다. clone, pull, push에 모두 이것으로 충분합니다. 비공개 저장소를 읽기만 한다면 Read-only로도 충분합니다.

Classic 토큰은 계정의 모든 저장소에 한꺼번에 적용됩니다. 저장소에 push하려면 repo 범위가 필요하고, .github/workflows 안의 파일을 바꾸려면 workflow 범위도 추가로 필요합니다. Classic은 간편하지만, 유출되면 계정 전체가 노출되는 위험이 있습니다.

만료 기간

GitHub는 여러 만료 기간을 제공하고, 원하는 날짜를 직접 지정할 수도 있습니다. 만료 없는 토큰도 만들 수 있지만, 권장하지 않습니다. 잊혀진 무기한 토큰은 보안 구멍이 되기 쉽습니다. 30~90일로 설정하고, 만료 전에 GitHub가 이메일로 보내는 알림을 보고 다시 발급하는 것이 좋습니다.

git push와 git clone에서 토큰 사용하기

토큰 사용은 생각보다 간단합니다. Git이 "Password"를 물으면, 비밀번호 대신 토큰을 붙여 넣으면 됩니다.

$ git push origin main
Username for 'https://github.com': your-login
Password for 'https://your-login@github.com': <토큰 붙여 넣기>

터미널에서는 비밀번호 문자가 보이지 않습니다. 정상입니다. 토큰을 붙여 넣고 Enter를 누르세요. Windows의 Git Bash에서는 Shift+Insert나 마우스 오른쪽 버튼으로 붙여 넣을 수 있습니다.

토큰으로 git clone하기

비공개 저장소도 같은 방식으로 clone합니다. git clone이 아이디와 토큰을 물어봅니다. 질문 없이 진행해야 한다면(예: 스크립트), 주소에 토큰을 직접 넣을 수 있습니다.

git clone https://your-login:<TOKEN>@github.com/user/project.git

단점도 있습니다. 토큰이 포함된 주소는 .git/config에 저장되고, 셸 기록에 남을 수 있습니다. clone 후에는 주소에서 토큰을 지우는 것이 좋습니다.

git remote set-url origin https://github.com/user/project.git

CI 시스템에서는 토큰을 파일에 적지 않고, 비밀 환경 변수로 전달합니다. GitHub Actions에는 현재 저장소용으로 GITHUB_TOKEN이 기본 제공되므로, 별도의 PAT가 필요 없는 경우가 많습니다.

GitLab: 토큰으로 git clone하기

GitLab에서는 프로필 설정의 Access tokens에서 토큰을 만듭니다. 코드 작업에는 read_repository와 write_repository 범위가 필요합니다. 방식은 같습니다. 사용자 이름에는 GitLab 아이디를, 비밀번호 자리에는 토큰을 넣습니다.

git clone https://oauth2:<TOKEN>@gitlab.com/group/project.git

GitLab은 개인용 토큰에 대해 사용자 이름 oauth2를 받아들입니다. 본인의 아이디를 넣어도 됩니다.

git pull과 fetch

공개 저장소라면 git pull과 git clone은 인증 없이 동작합니다. 아이디와 토큰은 비공개 저장소를 다루거나 git push를 할 때만 물어봅니다. 공개 프로젝트에서 git pull이 비밀번호를 요구한다면, 대부분 주소에 오타가 있는 경우입니다. GitHub는 존재하지 않는 저장소에도 비공개 저장소와 같은 응답을 주기 때문입니다.

Git Credential Manager란

push할 때마다 토큰을 입력하는 것은 불편합니다. 이 일을 맡는 것이 credential helper라는 보조 프로그램입니다. Git은 인증 정보가 필요할 때 이 프로그램을 호출합니다. Git이 서버 주소를 전달하면, 프로그램은 자신의 저장소에서 아이디와 비밀번호(또는 토큰)를 찾아 돌려줍니다.

Git Credential Manager(GCM)는 가장 편리한 credential helper입니다. GitHub와 Microsoft가 만든 크로스 플랫폼 프로그램입니다. 처음 push하면 로그인 창이나 브라우저가 열리고, GitHub에서 인증합니다(2단계 인증도 지원합니다). GCM이 토큰을 직접 받아 시스템의 안전한 저장소에 보관합니다. 이 방식이라면 PAT를 직접 만들 필요가 없습니다.

GCM은 GitHub, GitLab, Bitbucket, Azure DevOps를 지원합니다. Git for Windows에는 기본으로 설치되며, 설치 프로그램에서 고르는 credential helper 옵션이 바로 이것입니다.

credential.helper의 종류

Windows, macOS, Linux에서 인증 설정하기

이미 설정된 helper를 확인하려면 다음 명령을 씁니다.

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

Windows

Git을 설치할 때 기본 설정을 그대로 두었다면 GCM이 이미 동작합니다. 처음 push할 때 Git Bash, PowerShell, 또는 VS Code에서 GitHub 로그인 창이 열립니다. helper가 설정되지 않았다면 직접 켜세요.

git config --global credential.helper manager

macOS

Mac의 Git은 보통 osxkeychain을 사용합니다. 한 번 입력한 토큰은 키체인에 저장됩니다. 브라우저 로그인을 원한다면 Git Credential Manager를 설치하세요(Homebrew로는 brew install --cask git-credential-manager). 설치하면 스스로 설정을 등록합니다.

Linux

Linux에서는 GCM을 따로 설치합니다(.deb 패키지나 프로젝트 릴리스의 압축 파일). 그다음 설정을 하고 저장소 방식을 고릅니다.

git-credential-manager configure
git config --global credential.credentialStore secretservice

그래픽 환경이 없는 서버에서는 임시 캐시가 더 간단합니다.

git config --global credential.helper 'cache --timeout=3600'

GitHub용 대안: gh auth login

GitHub CLI를 설치했다면, gh auth login으로 브라우저 로그인을 진행할 수 있습니다. gh auth setup-git을 실행하면, Git이 인증 정보를 gh에서 가져오도록 설정됩니다. 명령 한 줄로 "Git Bash에 로그인"하는 편리한 방법입니다.

저장된 Git 비밀번호를 초기화하거나 갱신하는 방법

가장 흔한 상황은 토큰이 만료되었거나 계정을 바꾼 뒤에도 Git이 옛 정보를 계속 사용해서 Authentication failed가 나는 경우입니다. 저장된 항목을 지우면, 다음 push 때 Git이 다시 물어봅니다.

어떤 helper에서든 쓸 수 있는 공통 명령

printf "protocol=https\nhost=github.com\n\n" | git credential reject

Windows에서 인증 정보 초기화하기

"제어판" → "자격 증명 관리자" → "Windows 자격 증명"을 열고, git:https://github.com 같은 항목을 찾아 삭제합니다. 명령줄에서도 할 수 있습니다.

cmdkey /list | findstr git
cmdkey /delete:git:https://github.com

GCM을 쓰고 있다면, 계정에서 로그아웃하는 전용 명령도 있습니다: git credential-manager github logout <아이디>.

macOS

"키체인 접근"을 열고, 종류가 "인터넷 암호"인 github.com 항목을 찾아 삭제합니다. 터미널에서 하려면 다음과 같습니다.

git credential-osxkeychain erase
host=github.com
protocol=https

마지막 줄 다음에 빈 줄을 전달하기 위해 Enter를 한 번 더 누르세요.

Linux와 store

store를 쓴다면 ~/.git-credentials에서 github.com이 들어간 줄을 지웁니다. cache라면 git credential-cache exit을 실행합니다.

인증 오류의 원인과 해결 방법

Support for password authentication was removed

계정 비밀번호를 입력했습니다. 토큰을 만들어 Password 칸에 붙여 넣거나, Git Credential Manager를 설정하세요. 비밀번호를 묻지 않는데도 같은 오류가 나면, 옛 비밀번호가 저장소에 남아 있는 것입니다. 앞서 설명한 대로 그 기록을 지우세요.

git push: Authentication failed

자주 나오는 원인부터 순서대로 보면 다음과 같습니다. 토큰 만료, 토큰 취소, fine-grained 토큰에 이 저장소 접근 권한이 없거나 Contents가 읽기 전용임, 저장된 인증 정보가 다른 계정의 것임. Developer settings에서 토큰의 만료 기간과 권한을 확인하고, 저장된 인증 정보를 초기화하세요.

remote: Permission denied (403)

인증은 성공했지만, 이 계정에 저장소 쓰기 권한이 없습니다. 소유자에게 Collaborators로 추가해 달라고 하거나, 포크와 pull request로 작업하세요.

Repository not found

비공개 저장소의 경우 GitHub는 저장소가 존재하는지 알려 주지 않으므로, 토큰이 잘못되면 "not found"라고 표시합니다. git remote -v로 주소를, 토큰의 권한을 확인하세요.

git clone할 때마다 비밀번호를 묻는다

credential helper가 설정되지 않은 상태입니다. manager나 osxkeychain을 켜세요. 한 번 올바르게 입력하면 Git이 더 이상 묻지 않습니다. SSH로 바꾸는 방법도 있습니다.

토큰을 안전하게 보관하는 방법

• 권한은 최소한으로 하세요. repo가 들어간 classic 토큰 대신, 필요한 저장소로만 제한한 fine-grained 토큰을 쓰세요.
• 만료 기간을 정하고, 계속 연장하기보다는 다시 발급하세요.
• 토큰을 커밋하거나 remote 주소에 넣지 마세요. 토큰이 공개 저장소에 올라가면 GitHub가 자동으로 무효화하기도 하지만, 이미 유출된 것으로 생각하고 직접 삭제하세요.
• store 대신 시스템 보관소(GCM, 키체인)를 쓰세요.
• 토큰 하나는 기기 하나나 작업 하나에만 쓰세요. 유출되었을 때 그 토큰만 취소하면 됩니다.

정리

GitHub 비밀번호는 2021년 이후 HTTPS 방식의 Git 작업에서 쓸 수 없습니다. 현실적인 방법은 세 가지입니다. 브라우저에서 Git Credential Manager로 로그인하거나, GitHub 토큰을 만들어 비밀번호 자리에 입력하거나, SSH 키로 바꾸는 것입니다. 토큰은 Settings → Developer settings에서 만들고, credential.helper가 저장합니다. Authentication failed가 나면 대부분 토큰을 다시 발급하고 옛 인증 정보를 초기화하면 해결됩니다. GitHub 연결과 원격 저장소 작업은 Git 강의에서 실습으로 다룹니다.