GitHub App 토큰이 길어졌다: 40자 가정부터 지우는 연동 점검
어제까지 정상 동작한 GitHub 연동이 새 토큰에서만 실패한다면, 권한을 넓히기 전에 문자열이 지나가는 길을 보세요. 토큰을 받는 코드는 정상이어도 저장 필드나 프록시가 중간에서 값을 자르면 마지막 API 호출은 실패합니다.
GitHub는 2026년 10월 2일 GitHub App installation token의 stateless 형식 전환 완료를 발표했습니다. 신규 토큰은 기본적으로 ghs_APPID_JWT 형식이고, ghs_ 접두사를 유지하면서 기존 40자에서 약 520자로 길어집니다. 이는 사용자 개인 토큰 전체에 같은 규칙이 적용된다는 발표가 아닙니다.
무엇이 바뀌고 무엇을 확인할까
공식 안내에서 권한, 저장소 범위, 1시간 만료, 발급 REST API는 유지됩니다. 따라서 길이 문제를 해결하려고 권한이나 만료 가정을 바꾸는 대응은 이 변경의 원인을 겨냥하지 못합니다. 발급 단계와 소비 단계를 나눠 조사하세요.
임시 X-GitHub-Stateless-S2S-Token 헤더는 2026년 11월 30일 폐지 예정입니다. 기존·신규 형식을 검증한 뒤 기한 전에 제거하는 것이 공식 권고입니다. 전환 기간에 헤더를 남기는 일과 장기 운영 코드에 의존하는 일을 구분해야 합니다.
저장부터 요청까지 같은 값을 보존하기
먼저 토큰을 불투명 문자열로 취급하세요. 글자 수가 정확히 40이어야 한다는 검증, 좁은 DB 필드, 비밀 저장소 제한, Authorization 헤더를 거부하거나 자르는 미들웨어를 순서대로 확인합니다. JWT처럼 보인다는 이유로 직접 분해한 값을 인증의 근거로 삼을 필요는 없습니다.
실제 비밀 대신 합성 문자열로 저장·읽기·전달을 먼저 시험하세요. 입력 길이와 출력 길이, 성공 여부 같은 비밀이 아닌 증거만 남기고 원문 토큰은 로그에 넣지 않습니다. 약 520자를 새 고정 상한으로 박아 넣기보다 해당 시스템의 문서화된 제한을 확인하는 편이 낫습니다.
마스킹과 오류 로그도 함께 검사하기
토큰이 요청에서 살아남더라도 로그에서 노출되면 별개의 실패입니다. 기존 40자 패턴만 가리는 정규식은 긴 형식의 일부를 남길 수 있습니다. 정상 요청뿐 아니라 거부·재시도·예외 경로에서 Authorization 값이 출력되는지 합성 값으로 확인하세요.
GitHub 보안 문서는 최소 권한, 비밀 마스킹, 변환된 비밀 등록, 로그 점검을 함께 권고합니다. 팀의 점검표에는 저장 경로 담당자와 로그 경로 담당자를 모두 적으세요. 한쪽의 테스트 통과만으로 전체 연동이 안전하다고 결론 내리지 않는 것이 이 글의 운영 제안입니다.
작은 연동부터 검증하고 기한을 기록하기
개발자에게 생기는 실무 질문은 새 형식의 해독 방법보다 기존 시스템이 끝까지 문자열을 보존하느냐입니다. 이를 특정 커뮤니티의 합의라고 과장하지 않고, 공식 안내가 지적한 경계와 팀에서 재현 가능한 실험으로 답하는 것이 좋습니다.
비운영 환경의 작은 연동에서 합성 값 테스트, 실제 최소 권한 호출, 로그 점검을 마친 뒤 확대하세요. 이 순서는 이 글의 제안이며 GitHub가 모든 조직에 지정한 배포 절차는 아닙니다. 실패 구간·담당자·헤더 제거 기한을 한 기록에 묶으면 다음 점검이 쉬워집니다.