GitHub 통합 설정

이 가이드는 설정 가운데 GitHub에 특화된 부분을 다룹니다. GitHub은 지원하는 세 가지 코드 호스트 중 하나입니다 — GitLab 또는 Bitbucket 연결과, 한 워크스페이스에서 여러 코드 호스트를 함께 쓰는 방법은 코드 호스트 연결을 참고하십시오.

사전 준비

작업하려는 저장소에 접근할 수 있는 GitHub 계정
로그인에 쓸, 서버에 등록된 GitHub App (GitHub App 만들기 참고) 또는 붙여넣을 repo와 read:org 권한의 개인 액세스 토큰

GitHub로 로그인

기기 흐름 방식입니다. GitHub이 짧은 코드를 보여 주면 github.com에서 이를 승인하고, 서버가 자격 증명을 받습니다 — 콜백 URL도, 포트도, 노출할 것도 없습니다. 서버에 클라이언트 id가 있으면 언제든 사용할 수 있으며, 공식 빌드에는 이미 포함되어 있습니다.

설정 → 워크스페이스 → 프로필 및 신원 → 코드 호스팅으로 이동합니다(또는 온보딩 첫 단계에서)
GitHub 행에서 GitHub로 로그인을 클릭합니다
대화 상자에 여덟 자리 코드가 표시되고 브라우저에서 github.com/login/device가 열립니다. 코드는 이미 클립보드에 복사되어 있습니다
코드를 붙여넣고 앱을 승인한 뒤 돌아옵니다. 그러면 행이 스스로 your-username(으)로 로그인했습니다.로 바뀝니다

브라우저에서 작업을 마치는 동안 대화 상자를 닫아도 됩니다 — 서버는 코드가 만료될 때까지(약 15분) 계속 폴링하므로 로그인은 그대로 완료됩니다.

또는 토큰 붙여넣기

서버에 앱이 없거나, 필요한 계정에 앱이 설치되어 있지 않거나, 그냥 PAT를 쓰고 싶을 때의 대안입니다.

설정 → 워크스페이스 → 프로필 및 신원 → 코드 호스팅으로 이동합니다
GitHub 행에서 토큰 추가를 클릭합니다
repo와 read:org 권한이 있는 토큰(클래식)을 붙여넣고 저장합니다. 세분화된 토큰에는 저장소 Contents와 Pull requests(읽기 및 쓰기), 그리고 Checks와 Actions(읽기) 권한이 필요합니다.

토큰은 저장되는 즉시 확인되므로, 행에 이 토큰이 속한 계정이 표시될 수 있습니다. 토큰을 제거하려면 연결 해제를 클릭합니다.

확인: GitHub 행에 your-username(으)로 로그인했습니다.가 표시됩니다. 응답하는 자격 증명이 본인의 것이 아니면 접미사가 출처를 알려 줍니다 — “이 서버의 앱을 통해” 또는 “환경에서”입니다.

통합으로 얻는 것

기능	방법
PR 목록과 세부 정보	서버에서 앱 아이덴티티 또는 본인의 자격 증명으로 호출하는 GitHub REST API
검사 실행	GitHub Checks API
리뷰 게시	사용자가 승인해야 진행되는 단계로, 리뷰를 PR에 게시합니다
저장소 등록	체크아웃의 `origin` 리모트가 github.com 또는 gitlab.com / bitbucket.org를 가리키면 등록이 허용됩니다
에이전트의 GitHub 접근	자격 증명 브로커가 읽기 전용 토큰을 `GH_TOKEN` / `GITHUB_TOKEN`으로 주입합니다. 푸시는 Control Center를 거칩니다
알림 핑	서버가 GitHub 알림 받은편지함을 폴링해 “풀 리퀘스트에서 멘션됨”과 “리뷰 요청됨”을 발생시킵니다
사용자 프로필	프로필 호버 카드와 작성자별 PR 필터링

일부 경로는 더 저렴한 곳에서는 REST 대신 GraphQL API를 사용합니다 — PR 작성 화면의 브랜치 선택기에서 쓰는 브랜치 활동과, 리뷰 요청 알림이 아직 대기 중인지 판단하는 실시간 리뷰 상태가 그렇습니다.

GitHub 장애 확인하기

제목 표시줄에는 GitHub, Claude, OpenAI, Kimi 가운데 제공자 하나가 저하된 상태일 때 상태 칩이 표시됩니다. 모두 정상일 때는 이 칩이 숨겨집니다 — 칩이 있다는 사실이 문제를 알리는 것이지, 칩이 없다는 사실이 문제를 알리는 것은 아닙니다.

칩을 클릭하면 각 제공자의 상태와 새로 고침 버튼이 있는 플라이아웃이 열립니다. 상태는 2분마다 자동으로 새로 고쳐집니다.

에이전트가 GitHub에서 작동하는 방식

GitHub 워크트리에서 작업하는 에이전트는 항상 읽기 전용 GitHub 토큰을 받습니다. 푸시는 Control Center를 거치며, Control Center는 리모트에 푸시 규칙에 물은 뒤 에이전트가 결코 갖지 않는 쓰기 토큰으로 이를 전달합니다. 샌드박스 정책 구성을 참고하십시오
에이전트가 만든 커밋은 에이전트로서 작성됩니다 — 표시 이름에 (agent)를 붙이고, 에이전트 id를 키로 한 합성 주소를 사용하며, 사람으로 작성되는 일은 없습니다. 작업을 요청한 사람은 Co-Authored-By 트레일러로 크레딧을 받습니다
GitHub App이 구성되어 있으면, 브로커는 광범위한 토큰을 넘겨 주는 대신 실행마다 저장소 범위의 약 1시간짜리 세분화된 설치 토큰을 발급합니다. 설치는 실행이 대상으로 삼은 저장소의 소유자를 기준으로 해석되므로, 여러 계정에 설치된 앱 하나가 실행이 건드리는 계정에 맞게 범위가 정해집니다. 앱이 없으면 에이전트는 환경 변수 토큰을 받으며, 이 토큰은 읽기 전용으로 좁힐 수 없습니다. 이때 푸시 규칙은 git push에는 적용되지만, 토큰을 직접 쓰는 코드에는 적용되지 않습니다
토큰은 언제나 브로커의 것이며, 요청한 구성원 자신의 것이 아닙니다. 소유자가 아니고 GitHub를 연결하지 않은 구성원을 위해 동작하는 실행에는 서버의 토큰이 보류됩니다

문제 해결

PR 목록이 비어 있으면서 GitHub이 연결되지 않았다고 표시됩니다

이 서버에 GitHub 자격 증명이 없습니다. 코드 호스팅에서 로그인하거나 토큰을 붙여넣으십시오. 다른 forge의 저장소는 영향을 받지 않으며, GitHub의 저장소만 아무것도 제공하지 않습니다.

행에 “토큰 추가”는 있지만 “GitHub로 로그인”은 없습니다

서버에 클라이언트 id가 없기 때문입니다 — 자격 증명은 공식 빌드에만 포함되므로 소스에서 빌드한 경우에는 정상적인 상태입니다. GitHub App 만들기를 참고하십시오. 약 2분이면 되고, 서버 소유자만 한 번 하면 됩니다.

로그인 대화 상자에 제공자가 기기 코드를 반환하지 않았다고 표시됩니다

GitHub App은 있지만 Device flow 체크박스가 꺼져 있습니다. 앱 설정 (General → Device flow)에서 이 옵션을 켜고 다시 시도하십시오.

내 계정일 것으로 예상했는데 행에 “이 서버의 앱을 통해”가 표시됩니다

아직 로그인하지 않았으며, 지금 보이는 것은 서버의 앱 아이덴티티가 응답한 것입니다. 해당 행에서 GitHub로 로그인을 클릭하십시오.

세분화된 PAT에 병합 버튼이나 검사 상태가 표시되지 않습니다

토큰에 Contents와 Pull requests(읽기 및 쓰기), 그리고 Checks와 Actions(읽기) 권한이 필요합니다. 변경한 뒤 코드 호스팅에서 다시 붙여넣으십시오.

저장소 추가가 거부됩니다

등록에는 세 가지가 모두 필요합니다. 경로가 git 워크트리 안에 있고, origin 리모트가 있으며, 그 리모트가 지원되는 forge(github.com, gitlab.com 또는 bitbucket.org)를 가리켜야 합니다. 워크스페이스에 저장소 추가를 참고하십시오.

많이 사용한 뒤 한동안 모든 것이 작동을 멈춥니다

속도 제한 서킷 브레이커입니다. GitHub은 x-ratelimit-remaining: 0과 재설정 시각을 담은 403으로 기본 한도에 도달했음을 알립니다. 이런 응답을 보면 클라이언트는 시간 창이 지날 때까지 네트워크 호출 없이 이후 요청을 로컬에서 실패시킵니다. 따라서 재시도 폭주가 한도를 더 악화시킬 수 없습니다. 일시적 실패는 retry-after를 준수하며 지수 백오프로 최대 세 번까지 재시도됩니다.