GitHub CLI 자동 갱신 토큰, 복사해 둔 인증값은 어떻게 될까?

토큰이 만료된다고 매번 브라우저에서 다시 로그인해야 하는 것은 아니다. GitHub가 10월 21일 공개한 새 인증 방식은 짧게 유효한 액세스 토큰과 갱신 과정에서 교체되는 리프레시 토큰을 함께 보관한다. 필요한 시점에 gh가 새 액세스 토큰을 받아 인증을 이어간다. 다만 다른 프로그램에 복사해 둔 문자열까지 바뀌는 것은 아니다.

기존 로그인은 자동으로 전환되지 않는다

이번 기능은 사용자가 선택하는 공개 프리뷰다. CLI를 업데이트하더라도 기존 로그인과 수동으로 전달한 토큰의 동작은 그대로다. GitHub는 향후 새 로그인에서 기본값으로 삼을 계획이라고 밝혔지만, 10월 25일 기준 안내는 선택 적용이다. GitHub의 공개 프리뷰 발표에 적용 범위가 명시돼 있다.

액세스 토큰의 유효기간을 줄이면 유출된 액세스 토큰이 계속 사용될 수 있는 시간도 짧아진다. 사용자는 로그인 상태를 유지하면서 토큰 교체를 CLI에 맡긴다. 핵심은 인증을 사용하는 프로그램이 교체된 값을 받아 갈 수 있느냐다.

로그인 옵션과 Git helper를 함께 확인한다

GitHub CLI 2.103.0 이상에서 다음 명령으로 만료형 인증을 요청한다. 로그인 후에는 상태 명령으로 실제 발급된 인증의 만료 정보를 확인한다.

gh auth login --expiring
gh auth status

앞으로 로그인할 때마다 같은 선호 설정을 적용하려면 gh config set expiring_credentials enabled를 사용한다. 이 설정은 이후 로그인 요청에 적용하는 선택이며, 현재 저장된 토큰이 모두 교체됐다는 확인을 대신하지 않는다.

Git을 HTTPS로 사용한다면 gh auth setup-git으로 GitHub CLI를 credential helper로 설정한다. Git이 인증값을 요청할 때 gh가 유효한 토큰을 제공하고 필요하면 갱신하는 방식이다. Git 2.46 이상에서는 만료 시점이 지난 값을 캐시가 계속 보관하지 않도록 처리할 수 있다. 이전 Git에서도 동작하지만 업그레이드 권장 메시지가 나온다. 공식 인증 문서는 이 조건을 HTTPS Git 항목에서 설명한다.

자동 갱신이 닿지 않는 곳은 복사된 값이다

스크립트가 처음 한 번 gh auth token을 실행하고 결과를 저장해 계속 쓰면, 어느 순간 만료된 액세스 토큰으로 요청하게 된다. 공식 안내는 외부에서 토큰이 필요할 때마다 다시 조회하도록 권한다. 이 명령은 필요하면 갱신한 뒤 현재 값을 반환한다.

마지막 조건은 2.103.0 릴리스 노트에 별도로 적혀 있다. 환경변수로 인증하는 CI가 있다고 해서, 개인 컴퓨터의 로그인 옵션을 바꾸는 것만으로 그 CI에 갱신 기능이 생기지는 않는다.

gh auth refresh라는 이름도 구분해야 한다. 이 명령은 저장된 인증의 권한 범위를 조정하는 기능이다. 액세스 토큰을 자동 교체하기 위해 주기적으로 실행하는 명령이 아니다. 권한을 변경하면서 만료형 인증을 명시적으로 요청할 때는 --expiring 옵션을 사용할 수 있다. 명령 매뉴얼에서 지원 옵션을 확인할 수 있다.

지원 서버여야 만료형 토큰이 발급된다

발표 기준 지원 대상은 github.com과 ghe.com이며, GitHub Enterprise Server는 3.23부터다. 지원하지 않는 서버에서는 일반 비만료형 토큰으로 돌아간다. 따라서 옵션을 넣었다는 사실만으로 전환 성공을 판단하면 안 된다.

개인 개발 환경에서 gh와 HTTPS Git을 쓰는 경우에는 로그인과 helper부터 맞추면 된다. 오래 유효한 토큰을 전제로 만든 작업은 인증값을 어디서 읽고 얼마나 보관하는지 먼저 확인해야 한다. 전환의 기준은 토큰을 누가 발급했는지뿐 아니라, 바뀐 값을 누가 다시 받아 가는지다.

자주 묻는 질문