GitHub CLI 만료형 OAuth 토큰을 켜기 전에 gh auth token 저장 스크립트부터 확인해보세요

만료형 OAuth 토큰은 기존 로그인과 무엇이 다른가요?

2026-10-21 GitHub 변경 로그에 따르면 gh는 수명이 짧은 액세스 토큰과 돌아가며 바뀌는 리프레시 토큰을 함께 저장해요. 액세스 토큰이 만료될 때마다 gh가 백그라운드에서 새 토큰으로 바꾸고, 이때 리프레시 토큰도 새로 발급돼요.

달라지는 건 유출됐을 때의 수명이에요. 기존 토큰은 직접 폐기하기 전까지 유효하지만, 만료형 액세스 토큰은 몇 시간 안에 쓸 수 없게 된다고 해요. 정확한 만료 시간은 변경 로그와 문서 어디에도 숫자로 나와 있지 않아요.

어떻게 켜고 상태를 확인하나요?

켜는 방법은 두 가지이고, 둘 다 gh v2.103.0 이상이 필요해요.

출처는 위 변경 로그와 GitHub CLI 인증 문서이고, 확인일은 2026-10-27이에요.

켠 뒤에는 gh auth status로 이 자격 증명이 갱신 가능한 상태인지, 현재 액세스 토큰이 언제 만료되는지 볼 수 있어요. 이 명령은 만료가 가까운 토큰을 갱신하기도 해요. 갱신 없이 상태만 보고 싶으면 --no-refresh를 붙여요.

스코프를 바꿀 때는 gh auth refresh --scopes <스코프>를 쓰는데, 이때도 --expiring을 함께 주거나 설정을 켜 두세요. 문서 설명대로면 그렇지 않을 때 만료형 자격 증명이 일반 자격 증명으로 바뀔 수 있어요. 백그라운드 갱신은 스코프를 바꾸지 않아요.

git push가 막히지 않으려면 무엇을 준비하나요?

HTTPS로 git을 쓴다면 gh가 자격 증명 헬퍼를 맡아야 해요. 그래야 git이 요청할 때마다 gh가 갱신된 토큰을 내줘요. 아직 설정하지 않았다면 gh auth setup-git을 실행하세요. 만료형으로 로그인할 때도 설정을 안내해요.

git은 2.46 이상을 권장해요. 이 버전부터 gh가 캐시형 헬퍼가 만료된 자격 증명을 계속 들고 있는 걸 막을 수 있기 때문이에요. 더 낮은 버전도 동작하지만 업그레이드를 권하는 안내가 한 번 떠요. 먼저 git --version으로 팀 개발 환경의 버전을 확인해 보세요.

SSH로만 git을 쓰는 환경은 이 부분이 해당되는지 문서에 따로 나와 있지 않아요. 확인되지 않는 부분이니 HTTPS 사용 여부를 먼저 나눠서 보세요.

어떤 스크립트와 자동화가 깨질 수 있나요?

변경 로그는 gh auth token의 출력을 저장해 두고 나중에 다시 쓰지 말라고 안내해요. 저장한 토큰은 결국 만료되기 때문이에요. 필요할 때마다 gh auth token을 새로 호출하면 gh가 필요에 따라 먼저 갱신해서 내줘요. 갱신 없이 지금 값만 읽으려면 --no-refresh가 있어요.

아래는 점검 순서에 대한 제안이에요. 공식 문서가 정한 절차는 아니에요.

1. 저장소와 개인 스크립트에서 gh auth token을 검색해 결과를 변수가 아닌 파일, 환경 변수, 비밀 저장소에 옮겨 담는 곳을 찾아요.
2. 그 토큰을 다른 도구의 설정에 복사해 두는 곳(캐시 파일, 컨테이너 빌드 인자)을 따로 표시해요.
3. 장기간 유효한 토큰이 필요한 작업은 이번에는 옵트인하지 않는 쪽으로 분리해요. 변경 로그도 이런 워크플로에서는 아직 옵트인하지 말라고 해요.

GH_TOKEN이나 GITHUB_TOKEN으로 넣은 토큰은 만료형이 아니고 갱신도 되지 않아요. 릴리스 노트가 이 환경 변수 토큰은 갱신 대상이 아니라고 밝혀요. CI에서 쓰는 방식이 변경 로그에 따로 다뤄져 있지 않으니 CI는 지금 설정을 그대로 두는 게 안전해요.

내 환경에서는 어디까지 쓸 수 있나요?

github.com과 GHE.com에서는 지금 쓸 수 있어요. 서버가 만료형 자격 증명을 지원하지 않으면 --expiring을 줘도 일반 토큰으로 돌아가고, 그 사실을 알려 주는 안내가 나와요. GitHub Enterprise Server는 변경 로그에 GHES 3.23부터라고 적혀 있어요. 반면 인증 문서의 제한 사항에는 GitHub.com과 GitHub Enterprise Cloud만 나와요. 사내 서버를 쓴다면 버전별 문서를 먼저 확인하세요.

변경 로그는 앞으로 새 로그인의 기본값이 만료형으로 바뀔 거라고 하지만 날짜는 밝히지 않았어요. 그 전에 오늘 할 일은 하나예요. 팀 저장소에서 gh auth token을 검색해 저장해 쓰는 곳이 있는지 목록으로 만들고, 없으면 개발 PC 한 대에서 gh auth login --expiring을 먼저 시험해 보세요. 확인일은 2026-10-27이에요.