520자로 길어진 GitHub App 설치 토큰에 우리 코드가 괜찮은지 점검해보세요

무엇이 바뀌었나요?

GitHub 공지에 따르면 4월 27일에 시작한 단계별 적용이 끝났어요. 이제 새로 발급하는 설치 토큰은 기본으로 ghs_APPID_JWT 형식이에요. stateless는 GitHub이 토큰마다 서버에 상태를 따로 찾아보지 않아도 검증할 수 있는 방식을 말해요. 공지는 이 방식이 토큰 발급과 검증을 빠르게 하고 API 안정성을 높인다고 설명해요.

바뀐 것과 그대로인 것을 나누면 이래요. 확인일은 2026-10-12예요.

출처: GitHub Changelog, 2026-10-02 게시, 2026-10-12 확인.

접두사가 같아서 겉으로는 변화가 안 보여요. 그래서 길이에 의존한 코드만 조용히 걸릴 수 있어요.

이미 발급한 토큰은 어떻게 되나요?

변경 전에 발급한 토큰은 만료될 때까지 계속 동작한다고 공지가 밝혔어요. 설치 토큰은 한 시간 뒤 만료되니, 앱이 토큰을 새로 받을 때마다 새 형식을 만나게 돼요. GitHub Docs도 설치 토큰이 한 시간 뒤 만료된다고 적고, 토큰이 정확히 40자라는 가정이 더는 맞지 않을 수 있다고 알려요.

그래서 배포한 지 오래된 앱도 시간이 지나면 새 형식을 받아요. 오늘 문제가 없었다고 해서 안전하다고 볼 수는 없어요.

11월 30일에 무엇이 끝나나요?

X-GitHub-Stateless-S2S-Token 요청 헤더는 새 형식을 필요할 때 시험해 보라고 만든 임시 헤더예요. 공지는 이 헤더가 2026년 11월 30일에 폐기된다고 밝혀요. 그날 이후 GitHub은 헤더를 따르지 않고, 해당하는 앱은 항상 stateless 토큰을 받아요.

공지가 권하는 순서는 두 형식으로 앱과 워크플로를 검증한 다음, 운영 코드에서 헤더를 빼는 거예요. 헤더가 남아 있어도 11월 30일 뒤에는 효과가 없으니 급하게 삭제할 이유는 없지만, 시험용 코드가 운영에 남는 일은 막아 두는 편이 좋아요. 이 마지막 문장은 제안이에요.

우리 코드에서 어디를 확인하나요?

공지는 설치 토큰을 내용을 해석하지 않는 불투명한 문자열로 다루라고 해요. 그 기준으로 아래 네 곳을 찾아보라고 안내해요.

1. 토큰이 정확히 40자여야 통과하는 검증이나 옛 형식에 맞춘 정규식
2. 길이가 고정됐거나 짧은 데이터베이스 칸, 시크릿 저장소, 환경 변수
3. 긴 Authorization 헤더를 자르거나 거부하는 프록시, 게이트웨이, 미들웨어
4. 옛 토큰 형태만 찾는 로그 마스킹 규칙

네 번째는 놓치기 쉬워요. 마스킹 규칙이 옛 형태만 잡으면 새 토큰이 로그에 그대로 찍힐 수 있어요. 토큰은 한 시간 뒤 만료되지만 그 사이에는 쓸 수 있는 자격 증명이에요.

점검은 이렇게 해 보세요. 이 순서도 제안이에요.

• 저장소에서 ghs_와 40, {40} 같은 길이 조건을 검색해요.
• 토큰을 저장하는 칸의 최대 길이를 확인해요. 공지가 약 520자라고만 했으니 정확한 값에 맞추지 말고 넉넉한 상한을 잡아요.
• 스테이징 환경에서 새로 발급한 토큰으로 프록시를 거쳐 API를 한 번 호출해 보고, 로그에 토큰이 마스킹되는지 눈으로 확인해요.

공지가 답하지 않는 것은 무엇인가요?

공지에는 권장 칸 크기나 검증용 정규식이 없어요. 폐기 같은 취소 동작이 새 형식에서 어떻게 달라지는지도 적혀 있지 않아요. 약 520자라는 수치도 대략의 값이에요. 이런 부분은 우리 쪽에서 가정하지 말고, 적용 전에 위 두 공식 페이지의 최신 내용을 다시 열어 확인하세요.

정리하면, 520자로 길어진 토큰은 접두사가 같아서 눈에 띄지 않아요. 11월 30일 전에 길이 검증, 저장 칸, 프록시, 로그 마스킹 네 곳을 한 번 훑어 두면 돼요.