GitHub App installation token이 길어진 뒤, Mac CI는 어떻게 검증할까? 2026

Mac CI 인증이 토큰 형식 변경 뒤 실패합니다.
가장 먼저 토큰을 불투명한 문자열로 취급하고 길이 가정, 저장 공간, Authorization 헤더, 로그 마스킹을 차례로 검증하세요.

이 글은 GitHub App 관리자, GitHub Actions와 Mac CI 플랫폼 담당자, 기업 보안 및 감사 담당자를 위한 운영 점검 절차입니다.
토큰 발급·권한을 관리하거나 사용자 정의 Action, 프록시, 비밀 정보 저장 경로를 운영한다면 적용할 수 있습니다.

마지막 업데이트: 2026년 10월 10일. 형식과 정책은 GitHub의 공식 변경 공지와 설치 토큰 문서를 기준으로 확인했습니다.

고정 길이 가정과 불투명 문자열 처리를 먼저 구분합니다

GitHub는 2026년 10월 2일 무상태 GitHub App installation token의 단계적 배포 완료를 알렸습니다. 새로 발급되는 토큰은 ghs_로 시작하지만 길이가 예전 형식의 40자에서 약 520자로 바뀌었습니다. 공식 발표는 이 형식 변화를 확인하지만, 기업의 모든 사용자 정의 통합에서 문제가 생긴다는 뜻은 아닙니다. 공식 변경 공지

핵심은 토큰 내부 구조를 분석하지 않는 것입니다. 접두사 외의 모양이나 길이를 인증 규칙으로 사용하지 말고, 발급된 전체 값을 수정 없이 읽고 전달하고 저장하세요. 형식 변화는 호환성 검증 대상이지 권한 모델을 다시 설계해야 한다는 신호가 아닙니다.

유지되는 속성과 직접 검증할 속성을 분리하세요. 권한, 저장소 범위, 1시간 유효 기간, REST API 엔드포인트는 형식 변경으로 바뀌지 않았다고 공식 문서가 설명합니다. 설치 토큰 공식 문서에서 토큰 발급과 권한 동작을 확인하고, 팀이 추가한 길이 검사와 전달 로직은 별도로 살펴보세요.

길이 검사는 과거 고정값과 새 입력을 대조합니다

실패 원인을 찾을 때는 우선 토큰을 다루는 코드를 검색하세요. 사용자 정의 Action, 셸 스크립트, 정규식, 입력 검사기, 데이터베이스 스키마에 과거 길이를 요구하는 조건이 있는지 확인합니다. length == 40 같은 고정 비교뿐 아니라 최대 길이 제한, 정해진 형식만 허용하는 패턴도 대상입니다.

테스트에는 실제 비밀 값 대신 합성 값을 사용하세요. 예전 형식과 새 형식을 닮은 합성 입력을 준비하고, 각각이 읽기·전달·저장·복구 경로를 통과하는지 검사합니다. 테스트가 확인해야 하는 것은 특정 길이의 허용 여부가 아니라 전체 문자열이 변형 없이 이동하는지입니다. 내부 구성요소를 분리해 추출하거나 접두사 외의 내용을 재조립하는 코드가 있다면 제거하거나 안전한 전달 방식으로 바꾸세요.

저장 용량과 요청 전달은 각각의 경계에서 판정합니다

저장 경로와 HTTP 전송 경로는 서로 다른 제한을 가질 수 있습니다. 한쪽이 정상이라고 다른 쪽까지 통과한 것은 아닙니다. 아래 표의 판정은 특정 제품의 성능 점수가 아니라, 네 환경에서 증거를 수집할 때 사용할 합격 기준입니다.

저장 검사는 비밀 저장소, 환경 변수, 데이터베이스 열, 키 관리 인터페이스, 임시 파일 순으로 진행하세요. GitHub Actions 비밀 값의 취급 방식은 비밀 정보 공식 문서에서 확인할 수 있습니다. 임시 파일을 사용하는 구성이라면 파일 권한과 제거 시점도 함께 검토하세요. 여기서 목표는 저장 공간을 무조건 확대하는 것이 아니라, 실제 제한이 있는 지점을 찾아 필요한 수정만 하는 것입니다.

HTTP 전송은 Mac CI에서 GitHub API까지 실제 경로를 따라 확인합니다. HTTP 요청 필드의 처리 방식과 과도한 필드에 대한 일반 규칙은 RFC 9110을 참고할 수 있지만, 이 문서만으로 네 프록시나 게이트웨이의 설정 한계를 알 수는 없습니다. 격리 환경에서 합성 값을 보내고 각 홉의 응답, 변환, 로그를 확인하세요. 실제 운영 요청을 테스트 데이터로 복사하지 마세요.

로그 마스킹과 감사는 별도의 실패 경로로 봅니다

마스킹 필터가 과거 토큰 모양이나 길이에 의존하면 새 형식을 놓칠 수 있습니다. 빌드 출력만 검사하고 끝내지 말고 예외 보고서, 디버그 로그, 사용자 정의 Action의 출력까지 확인하세요. GitHub Actions 안전 사용 지침은 비밀 정보를 보호하는 운영 기준을 설명합니다.

검증 과정에서는 합성 비밀 값이 예상한 위치에서 가려지는지 확인하고, 시험 일시와 대상 경로, 결과, 수정 사항을 감사 기록에 남기세요. 실제 installation token을 로그 마스킹 시험 자료나 문서에 넣지 마세요. Actions가 제공하는 GITHUB_TOKEN과 GitHub App installation token은 발급 및 사용 맥락이 다르므로, GITHUB_TOKEN 공식 설명을 참고해 현재 워크플로에서 어느 자격 증명을 쓰는지부터 구분하세요.

FAQ: 저장·인증·마스킹 문제를 나눠 확인합니다

새 installation token을 받은 뒤 CI 인증이 실패하는 원인은 무엇인가요?

형식 변경만으로 인증 실패가 생긴다고 단정할 수는 없습니다. 먼저 사용자 정의 Action, 스크립트, 정규식이 이전 길이를 고정값으로 요구하는지 확인하세요. 다음으로 환경 변수나 저장 열의 잘림, 프록시의 Authorization 헤더 처리, 로그 마스킹 규칙을 분리해 점검하면 어느 구간에서 토큰이 변형되거나 거부되는지 좁힐 수 있습니다.

토큰이 길어졌다면 비밀 저장소의 필드 크기도 늘려야 하나요?

저장소 종류에 따라 다르므로 일괄 확대하지 마세요. GitHub Actions 비밀 값, 환경 변수, 데이터베이스 열, 키 관리 인터페이스, 임시 파일을 차례로 확인하고 새 형식의 합성 값이 온전히 저장되고 다시 읽히는지 시험하세요. 제한이 실제로 확인된 위치만 수정하면 됩니다. 토큰의 권한이나 유효 기간을 바꿀 이유는 아닙니다.

역방향 프록시가 긴 installation token 요청을 잘라낼 수 있나요?

특정 프록시가 반드시 자른다고 볼 수는 없습니다. Mac CI에서 GitHub API까지 이어지는 실제 요청 경로에 프록시, 게이트웨이, HTTP 클라이언트, 사용자 정의 미들웨어가 있는지 확인하세요. 격리 환경에서 합성 토큰으로 요청을 보내고, 거부·잘림·기록 여부를 각 구간의 로그와 응답으로 판정합니다. 설정과 동작은 사용 중인 구성에서 직접 확인해야 합니다.

GitHub Actions 로그 마스킹은 새 토큰 형식에도 적용되나요?

이전 접두사나 고정 길이만 찾는 사용자 정의 필터라면 새 형식을 놓칠 수 있습니다. 실제 비밀 값 대신 합성 문자열을 사용해 빌드 출력, 예외 보고서, 디버그 로그에서 값이 가려지는지 시험하세요. GitHub Actions의 비밀 처리 문서와 안전한 사용 지침을 함께 검토하고, 마스킹 통과 여부를 감사 기록에 남기면 검증 근거를 보존할 수 있습니다.

배포 판단은 전 구간 증거와 권한 불변 여부로 마무리합니다

운영 반영 전에는 다음 순서로 검증하세요.

• 테스트 환경에서 새 형식과 예전 형식을 닮은 합성 입력을 준비하고, 실제 토큰은 시험 자료에서 제외합니다.
• Action, 스크립트, 정규식, 입력 검사기를 검색해 고정 길이와 과거 형식 전용 조건을 기록합니다.
• 비밀 저장소에서 환경 변수와 파일까지 이어지는 경로를 따라 값의 쓰기·읽기 결과가 일치하는지 확인합니다.
• 프록시, 게이트웨이, HTTP 클라이언트를 포함한 실제 요청 경로에 합성 값을 보내 거부·잘림·기록 여부를 검사합니다.
• 빌드 출력, 예외 보고서, 디버그 모드에서 마스킹을 확인하고 결과를 감사 기록에 남깁니다.
• 저장소 범위, 권한, 유효 기간, API 엔드포인트가 형식 변경 때문에 바뀌지 않았는지 검토한 뒤 증거에 따라 통과·수정 후 재검증·보류를 결정합니다.

임시 X-GitHub-Stateless-S2S-Token 요청 헤더를 사용하는 통합은 별도 추적이 필요합니다. GitHub는 이 임시 헤더가 2026년 11월 30일 이후에는 작동하지 않는다고 안내했습니다. 해당 헤더를 테스트에 사용하고 있다면 관련 공식 공지에 맞춰 제거 일정을 기록하고, 일반적인 Authorization 전달 경로의 합격 근거와 혼동하지 마세요.

새 토큰 형식만을 이유로 Mac CI 노드를 교체하거나 권한 모델을 다시 만들 필요는 없습니다. 먼저 현재 Action·프록시·로그 경로의 호환성을 입증하세요. 다만 개인별 Mac에 환경이 흩어져 있고 장비를 계속 직접 관리하는 방식은 공통 운영 기준을 적용하기 어렵고, 사용하지 않는 시간에도 하드웨어 비용이 남을 수 있습니다. 반대로 장기간 고정된 고부하 작업이나 물리 인터페이스가 꼭 필요한 팀에는 임대보다 자체 장비가 맞을 수 있습니다. 자체 장비 비용을 검토할 때는 맥 미니 요금 안내를 기준으로 구매 및 운영 항목을 함께 비교하세요. Mac CI 실행 환경까지 함께 검토한다면 실제 Mac과 가상화 환경의 차이를 확인하고, 임시 검증이나 팀 공용 실행 환경이 필요할 때는 VNC·SSH·웹 콘솔로 접속하는 실제 Mac을 주 단위·월 단위·분기 단위로 이용하는 MacDate 방식도 비교해 보세요. 팀의 자격 증명 주입과 로그 정책은 어느 방식을 선택하든 별도로 검증해야 합니다.