GitHub App 설치 토큰: 요청별 재정의 헤더 도입
(github.blog)GitHub은 GitHub App 설치 토큰에 대한 새로운 토큰 형식의 점진적 도입을 지원하기 위해 X-GitHub-Stateless-S2S-Token이라는 임시 요청 헤더를 도입했습니다. 이 헤더를 통해 개발자는 새로운 토큰 형식의 영향을 미리 테스트하고, 필요한 경우 기존 토큰 형식을 유지할 수 있습니다.
주요 내용
X-GitHub-Stateless-S2S-Token 헤더
POST /app/installations/:installation_id/access_tokens 요청 시 이 헤더를 설정하여 서버 측의 토큰 형식 롤아웃 결정을 재정의할 수 있습니다.
| 헤더 값 | 효과 |
|---|---|
enabled |
롤아웃 진행 상황과 관계없이 상태 비저장(JWT 형식) 토큰을 반환합니다. |
disabled |
통합이 롤아웃에 포함되었더라도 상태 저장(기존 불투명) 토큰을 반환합니다. |
| (없음) | 일반적인 롤아웃 동작을 따릅니다. |
새로운 토큰 형식 (ghs_ 접두사 JWT)
새로운 상태 비저장 토큰은 ghs_ 접두사가 붙은 JWT 형식이며, 길이가 약 520자로 길고 두 개의 점(.)을 포함합니다. 기존 상태 저장 토큰은 짧은 불투명 문자열이며 점이 없습니다.
개발자는 다음 사항을 확인하여 애플리케이션이 새로운 토큰 형식을 올바르게 처리하는지 검증해야 합니다.
- 하드코딩된 토큰 길이 가정 제거
- 토큰 유효성 검사에 사용되는 정규식 업데이트 (권장 정규식:
ghs_[A-Za-z0-9\._]{36,}) - 토큰 저장을 위한 데이터베이스 컬럼이 최소 520자 이상을 허용하도록 설정
- 토큰 검사 또는 유효성 검사 코드가
ghs_토큰을 불투명 문자열로 처리
준비 방법
enabled로 테스트: 옵트인 헤더를 사용하여 엔드포인트를 호출하고 앱이 새로운 토큰 형식을 종단 간에 수락하는지 확인합니다.disabled로 테스트: 앱이 기존 불투명 형식으로도 작동하는지 확인하여 상태 비저장 토큰을 일시적으로 사용할 수 없는 경우에도 정상적으로 작동하는지 확인합니다.- 헤더 제거: 두 경로 모두 유효성이 검증되면 헤더를 제거합니다. GitHub의 롤아웃이 토큰 형식을 자동으로 관리합니다.
참고 사항
- 이 헤더는 임시적이며, 향후 별도로 공지될 시점에 더 이상 지원되지 않을 예정입니다.
- 기존 앱 설치 토큰은 만료될 때까지 계속 작동합니다.
- 이 변경 사항은 GitHub Enterprise Cloud 및 Data Residency 환경에 적용되며, GitHub Enterprise Server는 영향을 받지 않습니다.
- 향후 롤아웃은 GitHub App 설치 서버-투-서버 토큰(Actions
GITHUB_TOKEN포함)에만 새로운 토큰 형식을 적용할 예정입니다.
자세한 내용은 GitHub 블로그에서 확인할 수 있습니다.