깃허브 앱 토큰 형식 변경, 지금 바로 앱 호환성을 테스트하세요!
깃허브(GitHub)는 2026년 4월 발표에 따라 새로운 설치 토큰 형식을 도입하며, 토큰 형식 변경(Token Format Change)을 예고함
개발자는 임시 헤더(Temporary Header)를 사용하여 새로운 토큰 형식(Stateless Token)을 강제로 활성화하거나 비활성화하여 앱 호환성을 검증할 수 있음
X-GitHub-Stateless-S2S-Token 헤더를 통해 토큰 형식 제어(Token Format Control) 가능하며, enabled/disabled 값으로 동작을 설정
깃허브(GitHub)는 향후 몇 주 안에 헤더 지원을 중단하고, 모든 앱에 새로운 토큰 형식을 적용할 예정
X-GitHub-Stateless-S2S-Token 헤더의 작동 방식
본문에 따르면 X-GitHub-Stateless-S2S-Token 헤더는 POST /app/installations/:installation_id/access_tokens API 요청에 추가되어 토큰 생성 방식(Token Generation Method)을 제어한다.
enabled: JWT 형식의 토큰(Stateless Token) 반환, 깃허브(GitHub) 롤아웃 여부와 관계없이 적용
disabled: 기존 형식의 토큰(Stateful Token) 반환, 롤아웃 대상 앱에도 기존 토큰 반환
(absent): 깃허브(GitHub)의 롤아웃 정책에 따라 토큰 형식 결정
이 헤더는 깃허브(GitHub) 앱의 호환성 테스트(Compatibility Test)를 돕기 위한 임시 수단이며, 롤아웃 완료 후에는 제거될 예정이다.
새로운 토큰 형식(Stateless Token)의 특징
글에 따르면 새로운 토큰은 ghs_ 접두사를 가지는 JWT(JSON Web Token) 형식이며, 기존 토큰보다 길이가 길고(약 520자), 두 개의 점(.)을 포함한다.
토큰 길이 가정 금지: 하드코딩된 토큰 길이 가정은 보안 취약점(Security Vulnerability)을 유발하므로 지양
정규식 업데이트: 설치 토큰 검증에 사용되는 정규식(Regex)은 새로운 형식에 맞게 수정(Modification) 필요
데이터베이스(Database) 컬럼: 토큰 저장 컬럼 및 헤더 설정은 최소 520자 이상을 수용하도록 확장(Expansion)
토큰 검증 코드: ghs_ 토큰을 불투명 문자열로 처리하도록 수정(Modification)
새로운 토큰 형식 도입은 기존 시스템(Legacy System)과의 호환성 문제를 야기할 수 있으므로, 꼼꼼한 검증이 필요하다.
롤아웃(Rollout) 기간 동안의 대응 전략
본문에서는 롤아웃(Rollout) 기간 동안 개발자가 두 가지 토큰 형식(Token Format) 모두에 대응할 수 있도록 권장한다.
사전 테스트: X-GitHub-Stateless-S2S-Token: enabled 헤더를 사용하여 새로운 토큰 형식(Stateless Token)을 미리 테스트
장애 대응: X-GitHub-Stateless-S2S-Token: disabled 헤더를 사용하여 기존 토큰 형식(Stateful Token)으로의 전환을 대비
헤더 제거: 두 가지 토큰 형식 모두 검증 완료 후, 프로덕션 코드에서 헤더를 제거(Removal)
깃허브(GitHub)는 롤아웃 과정에서 발생하는 문제에 대해 깃허브 지원팀(GitHub Support) 또는 깃허브 커뮤니티(GitHub Community)를 통해 도움을 받을 수 있도록 안내한다.
토큰 형식 검증 방법
글에 따르면 토큰 형식은 ghs_ 접두사 뒤에 있는 점(.)의 개수를 통해 확인할 수 있다.
JWT 형식(Stateless Token): 점(.) 2개 포함
기존 형식(Stateful Token): 점(.) 없음
이러한 검증 방법은 토큰 유효성 검사(Token Validation) 로직에 통합되어야 하며, 토큰 형식에 따라 다른 방식으로 처리해야 한다.
데이터 미저장 정책(Zero-Retention Policy)**을 준수하는 시스템에서는 토큰의 상태를 저장하지 않으므로, 토큰 형식 검증이 더욱 중요해진다.
