GitHub App 토큰이 길어져 검증에 실패한다면

세 줄 요약

GitHub App의 새 설치 토큰은 기존 40자보다 길지만 ghs_ 접두사는 유지한다.
약 520자는 고정 규격이 아니다. 발급받은 문자열 전체를 보관하고 전달해야 한다.
발급 요청 자체의 오류와 발급 후 토큰이 거부되거나 잘리는 문제는 나눠 확인한다.

40자를 520자로 바꾸는 것만으로 끝내면 안 된다

GitHub App 설치 토큰을 받는 입력란이나 코드에 정확히 40자만 허용하는 규칙이 있다면 수정 대상이다. GitHub는 10월 2일 새 형식의 배포 완료를 알렸다. 새로 발급되는 설치 토큰은 기본적으로 ghs_APPID_JWT 형식이며 길이는 약 520자다. 접두사가 같아도 나머지 문자열의 모양과 길이는 달라졌다.

‘약 520자’를 새 고정 길이 조건으로 바꾸면 안 된다. GitHub의 전환 안내는 길이를 하드코딩하지 말고 설치 토큰을 내부 해석에 의존하지 않는 문자열로 취급하도록 요구한다. 밑줄과 점을 허용하지 않는 기존 정규식도 함께 살펴야 한다.

입력란을 고쳤어도 저장이나 전달에서 잘릴 수 있다

점검 대상은 토큰을 처음 받는 코드만이 아니다. GitHub가 지목한 검증·저장·전달·로그 처리를 실제 연동 경로에 대입하면 다음과 같다.

위치	확인할 내용
검증 코드	40자 고정 조건이나 옛 형식만 받는 정규식이 남아 있는지 확인한다.
저장 계층	DB 필드·비밀 저장소·환경변수 전달 과정의 길이 제한이 값을 자르는지 확인한다.
HTTP 전달	프록시·게이트웨이가 긴 Authorization 헤더를 거부하거나 줄이는지 확인한다.
로그 마스킹	옛 토큰 모양만 가려 새 형식이 기록에 드러나는지 확인한다.

문자열을 더 길게 저장하는 것과 안전하게 저장하는 것은 함께 충족해야 한다. GitHub App 보안 지침은 플랫폼의 민감정보용 저장 수단을 사용하고, 웹 앱에서는 서버 측 토큰 암호화와 접근 통제를 적용하도록 안내한다. 길이 문제를 확인하려고 실제 토큰 전체를 로그에 남기는 방식은 피해야 한다.

토큰을 못 받는 문제인지, 받은 뒤 못 쓰는 문제인지 가른다

설치 토큰을 발급받는 API는 바뀌지 않았다. 공식 생성 절차는 앱의 JWT를 만든 뒤 설치 ID로 토큰 발급을 요청하고, 응답의 설치 토큰을 사용하는 흐름이다. 앱을 식별하는 ID와 설치를 식별하는 ID는 혼동하지 않아야 한다.

발급 단계에서는 요청에 넣은 JWT와 설치 ID를 확인한다. 이미 토큰 응답을 받은 상태라면 그다음 저장·조회·HTTP 요청까지 같은 값이 보존되는지 살핀다. 이는 오류가 생긴 위치를 좁히는 점검 순서다. 토큰이 길어졌다는 이유만으로 모든 인증 실패의 원인을 길이 제한으로 단정할 수는 없다.

응답에는 만료 시각과 권한 정보도 들어 있다. 새 형식에서도 설치 토큰의 한 시간 유효기간과 접근 범위는 유지된다. Octokit을 이용하면 발급과 만료 후 재발급을 SDK에 맡길 수 있지만, 별도로 만든 저장 계층이나 프록시의 길이 제한까지 SDK가 고쳐 주는 것은 아니다.

유효한 토큰은 만료 전까지 캐시해 재사용하는 것이 GitHub의 권장 방식이다. 매 API 요청마다 토큰을 새로 발급하기보다 캐시에 유효한 값이 있는지 확인하되, 저장 과정에서 문자열이 온전히 유지되는지 함께 점검해야 한다.

옛 형식을 요청하는 임시 헤더는 11월 30일 끝난다

전환 시험용 X-GitHub-Stateless-S2S-Token 헤더는 영구적인 호환 기능이 아니다. GitHub는 2026년 11월 30일부터 이 헤더를 더 이상 반영하지 않으며, 두 형식의 호환성을 검증한 뒤 그 전에 운영 코드에서 제거하도록 안내한다.

5월 안내의 적용 범위는 GitHub Enterprise Cloud와 Data Residency 환경이며 GitHub Enterprise Server는 제외돼 있다. 개인 액세스 토큰이나 사용자 액세스 토큰까지 같은 길이로 바뀌었다고 해석해서는 안 된다. 이번 수정의 목표는 설치 토큰의 내부 모양을 맞히는 것이 아니라, GitHub가 발급한 값을 인증 요청까지 손실 없이 전달하는 것이다.