GitHub CLI 만료 토큰 프리뷰: 자동 갱신으로 인증 바꾸기

GitHub CLI가 만료되는 액세스 토큰과 자동 갱신을 선택할 수 있는 공개 프리뷰를 시작했다. 2026년 10월 21일 공식 변경 기록에 따르면 v2.103.0부터 로그인할 때 --expiring을 지정할 수 있다. CLI는 짧게 유지되는 액세스 토큰과 교체되는 갱신 토큰을 함께 보관한다. 매번 로그인하는 불편을 줄이면서 유출된 액세스 토큰이 무기한 유효하게 남는 문제를 줄이는 방향이다.

달라진 인증 방식

기존 로그인은 그대로 유지된다. 이번 기능은 선택 사항이며 직접 제공한 토큰의 성격을 자동으로 바꾸지 않는다. --expiring은 갱신 가능한 자격증명을 요청하는 설정이지 모든 서버가 반드시 발급한다는 보장은 아니다. github.com과 ghe.com에서 이용할 수 있고 GitHub Enterprise Server는 3.23부터 지원한다. 그보다 오래된 서버에서는 기존의 비만료 방식으로 돌아간다고 GitHub는 설명했다.

액세스 토큰이 짧아져도 계정 자체의 권한이 줄어드는 것은 아니다. 갱신 토큰과 이를 보관한 컴퓨터가 함께 탈취되면 별도의 대응이 필요하다. 이번 변경을 권한 최소화나 안전한 저장소의 대체재로 이해하면 안 된다.

설치 전 확인

아래는 공식 문서 기준의 macOS·Homebrew 및 POSIX 셸 예시이며 이 기사 작성을 위해 실제 계정의 로그인 설정을 변경하지 않았다. Windows는 공식 설치 안내의 Winget·Scoop 등을 사용하고, Linux는 공식 배포판 설치 절차를 따른다. gh 2.103.0 이상, 브라우저 로그인 가능 환경, 해당 호스트에 접근할 네트워크가 필요하다. HTTPS Git 인증까지 연결한다면 Git 2.46 이상을 권장한다. 오래된 Git의 자격증명 캐시가 만료 토큰을 재사용하는 문제를 피하기 위해서다.

# 처음 설치하는 경우
brew install gh
# 이미 설치했다면 위 명령 대신 brew upgrade gh
gh --version
git --version
gh auth status --hostname github.com

기존에 어떤 계정과 호스트를 쓰는지 먼저 확인한다. GH_TOKEN 같은 환경변수로 인증하는 자동화와 로컬 OAuth 로그인을 혼동하지 않는 것도 중요하다. 키체인을 사용할 수 없는 환경에서는 gh가 평문 파일 저장으로 대체할 수 있으므로 로그인 후 저장 위치를 확인한다. 편의를 이유로 --insecure-storage를 기본값처럼 쓰지 않는다.

최소 로그인

gh auth login --hostname github.com --git-protocol https --web --expiring
gh auth status --hostname github.com

브라우저의 승인 절차를 마친 뒤 auth status에서 로그인 계정과 만료 자격증명 상태를 확인한다. 실제 만료 시각은 서버가 발급한 값으로 확인하며 기사에서 고정된 수명을 가정하지 않는다. 토큰을 보여 주는 옵션을 붙이거나 인증 출력 전체를 공개 이슈에 복사하지 않는다. 서버가 기능을 지원하지 않으면 비만료 토큰이 발급될 수 있으므로 명령이 성공했다는 사실만으로 만료 방식을 확인했다고 결론내리지 않는다.

읽기 전용 실무 예제

다음은 자신이 접근할 수 있는 저장소의 열린 PR 목록을 받아 변경 검토 대상을 좁히는 예시다. OWNER와 REPO를 실제 값으로 바꾼다. 토큰을 추출하거나 파일에 저장하지 않고 gh가 API 호출 시 자격증명을 관리하게 한다.

gh api repos/OWNER/REPO/pulls \
  --method GET \
  -f state=open \
  -f per_page=20 \
  --jq '.[] | {number, title, user: .user.login}'

결과에는 PR 번호·제목·작성자 객체가 순서대로 나온다. 열린 PR이 없으면 출력이 없을 수 있으며 인증 실패와 다르다. 이 예시는 GET 요청으로 PR을 생성하거나 병합하지 않는다. gh는 필요한 시점에 토큰을 갱신하므로 사용자가 따로 갱신 명령을 주기적으로 실행할 필요는 없다.

Git 연결과 옵션

HTTPS Git에서도 같은 자격증명을 사용하려면 먼저 현재 credential helper 값을 기록한다. 다음 설정은 사용자 Git 설정에 영향을 줄 수 있으므로 회사의 기존 자격증명 관리 정책을 확인하고 적용한다. SSH 기반 Git 인증을 반드시 바꿀 필요는 없다.

git config --global --get-regexp credential
gh auth setup-git --hostname github.com

모든 새 로그인에서 만료 방식을 선호하려면 gh config set expiring_credentials enabled를 사용할 수 있다. 한 번만 시험하려면 전역 기본값을 바꾸지 말고 로그인 명령의 --expiring만 사용한다. --hostname은 개인 GitHub와 기업 호스트를 구분하고, --git-protocol https는 Git 전송 방식을 정한다. 토큰을 한 번 추출해 다른 도구에 오래 보관하는 확장은 만료 뒤 실패할 수 있다. 외부 연동이 필요하면 공식 지침과 해당 도구의 갱신 지원을 검토하되, 토큰을 로그로 출력하는 방식은 피한다.

권한과 비용

CLI 설치 자체가 새 유료 구독을 만들지는 않는다. 다만 연결하는 GitHub 상품과 API 제한은 계정·플랜에 따른다. 브라우저 승인 화면에서 요청 권한을 확인하고, 읽기 예제에 필요 없는 추가 scopes를 무심코 요청하지 않는다. 요청과 응답은 지정한 GitHub 호스트로 전송된다. 비공개 PR 제목도 민감정보일 수 있으므로 결과 파일의 보관과 공유 범위까지 관리한다.

오류를 좁히는 순서

unknown flag가 나오면 먼저 gh --version으로 구버전 여부를 확인한다. 만료 뒤 401이 발생하면 auth status와 환경변수 인증 여부, 외부 도구가 저장한 오래된 토큰을 점검한다. API의 404는 저장소 경로 오류뿐 아니라 비공개 저장소 권한 부족일 수도 있다. 403은 접근 정책·권한·요청 제한 등을 확인해야 하며 무조건 재로그인부터 반복하지 않는다. 갱신에는 네트워크가 필요하므로 프록시와 방화벽 정책도 진단 대상이다.

되돌리기와 폐기

전역 기본값을 설정했다면 기존 값을 기록한 뒤 복구한다. 이전에 설정하지 않았던 테스트 환경에서는 다음처럼 기본 선호를 끄고 다음 로그인에서 비만료 방식을 요청할 수 있다. 이는 서버의 발급 결정을 강제하는 수단은 아니다.

gh config set expiring_credentials disabled
gh auth login --hostname github.com --web --expiring=false
# 해당 기기의 저장된 로그인만 제거하려면 별도로 실행
# gh auth logout --hostname github.com --user YOUR_LOGIN

gh auth logout은 로컬 인증 설정을 제거할 뿐 서버 토큰을 폐기하지 않는다. 유출이 의심되면 GitHub 설정의 Applications에서 GitHub CLI 접근을 철회해야 한다. 이 조치는 다른 기기의 CLI 토큰에도 영향을 줄 수 있으므로 범위를 확인한다. setup-git으로 바뀐 helper는 앞서 기록한 값으로 되돌리고, CLI까지 제거하려면 Homebrew 설치 환경에서 brew uninstall gh를 사용한다. 프로그램 삭제만으로 계정 접근권이 폐기된다고 생각해서는 안 된다.

출처