GitHub App을 기업에 설치해도 저장소 코드는 열리지 않아요
회사 GitHub 설정을 자동으로 읽는 스크립트가 퇴사한 담당자의 개인 토큰에 연결돼 있다면, 사람을 바꾸는 일과 시스템을 고치는 일이 얽히게 돼요. GitHub가 10월 23일 기업 계정에 GitHub App을 설치하는 기능의 정식 출시를 알렸어요. 기업 정책과 관리 설정을 다루는 자동화에서 classic PAT를 대체할 선택지가 넓어진 거예요. 흥미로운 점은 기업 전체에 설치했다는 말이 모든 저장소의 코드를 읽는다는 뜻은 아니라는 데 있어요.
기업 정책을 다루는 앱이 할 수 있는 일
발표에는 기업 저장소 정책과 ruleset, 우회 요청 읽기, IP 허용 목록 같은 관리 기능이 포함돼 있어요. 예를 들어 규칙을 우회해 달라는 요청을 모아서 검토 화면에 보여 주는 앱이라면 Enterprise bypass requests의 읽기 권한을 살펴볼 수 있어요. 요청을 읽는 작업과 규칙 자체를 바꾸는 작업은 서로 다른 권한을 요구해요. 새 기능을 쓴다는 이유로 모든 쓰기 권한을 한꺼번에 켤 필요는 없어요.
기업 설치는 기업 권한만 부여해요. 조직이나 저장소 권한이 앱 등록에 함께 있어도 기업 설치만으로는 그 권한이 생기지 않아요. 사내 개발팀 두 곳의 저장소 코드를 읽는 도구를 만든다면, 관련 조직에 별도로 설치하고 필요한 저장소 접근을 부여해야 해요. 기업 설정을 볼 수 있는데 코드 조회는 거절되는 상황이 반드시 설치 실패를 뜻하는 것은 아니에요.
설치 하나와 회사 전체를 구분해 봐요
가상의 acme 기업에 web팀과 mobile팀 조직이 있다고 해 볼게요. 같은 앱을 기업과 두 조직에 설치하면 설치는 세 개예요. 기업 설치 토큰을 web 조직 토큰처럼 사용할 수 없고, web 설치 토큰으로 mobile 경계를 넘을 수도 없어요. 아래 그림은 이 예시를 설명하기 위해 직접 그린 것으로, GitHub 제품 화면이나 실제 고객 계정의 구성은 아니에요.
그래서 토큰 캐시의 키를 app 이름 하나로만 잡으면 곤란해요. 같은 앱이더라도 어느 설치를 위한 토큰인지 구분해야 하거든요. 설치 ID를 함께 저장하면 기업 정책을 읽는 작업과 특정 조직 코드를 읽는 작업이 같은 토큰을 잘못 재사용하는 실수를 줄일 수 있어요. 이는 문서의 계정 경계를 코드 구조에 옮기는 구현 예시예요.
앱의 권한과 사용자의 권한이 만나는 곳
설치 토큰으로 동작할 때와 사용자를 대신할 때도 차이가 있어요. 사용자 access token의 성공 여부는 앱과 사용자 양쪽의 권한에 달려요. 앱에 쓰기 권한이 있어도 사용자가 읽기만 할 수 있다면, 사용자 대신 실행하는 작업이 그 사람의 권한을 넘어설 수는 없어요. 반면 installation access token은 해당 설치에 부여한 앱 권한을 기준으로 동작해요.
설치 토큰은 앱의 JWT와 대상 installation ID를 사용해 발급해요. 공식 문서는 POST /app/installations/INSTALLATION_ID/access_tokens와 1시간의 유효기간을 설명해요. Octokit은 토큰 생성과 만료 후 재생성을 도울 수 있어요. 짧은 유효기간은 개인 PAT를 계속 복사해 두는 방식과 다른 운영 장점이 있지만, 앱의 private key를 보호하고 설치별 토큰을 구분하는 일은 여전히 필요해요.
개인 토큰을 바꾸기 전에 남는 질문
기존 스크립트가 기업 정책 조회와 여러 조직의 코드 조회를 한 번에 처리했다면, 토큰 문자열만 교체해서 끝나지 않을 수 있어요. 기업 작업과 조직 작업을 나누고 각 API가 GitHub App을 지원하는지 확인해야 해요. 모든 기업 GraphQL 작업이 앱을 지원하는 것은 아니며, 사용자 토큰과 설치 토큰 중 어떤 방식이 필요한지도 작업마다 달라요. 읽기 작업부터 옮기면 결과를 비교하면서 접근 경계를 이해하기 좋아요.
출시 단계에는 자료 간 시차도 있어요. 10월 23일 changelog는 정식 출시라고 안내하지만, 오늘 확인한 설치 문서에는 public preview 문구가 남아 있어요. 이 글은 출시 상태는 날짜가 있는 발표를, 설치와 권한 범위는 현재 문서를 기준으로 읽었어요. 실제로 바뀌는 핵심은 개인의 광범위한 권한을 그대로 복제하는 대신, 어떤 계정에서 어떤 일을 하는 앱인지 드러내며 자동화를 설계할 수 있다는 점이에요.
출처와 더 읽을 자료
GitHub Docs · Enterprise installation