# GitHub 연결

> 워크스페이스에 GitHub 계정과 저장소를 연결하는 방법과 조직 저장소 승인 절차를 안내합니다.

Specify는 GitHub 저장소를 문서의 근거로 사용합니다. 저장소를 연결하면 에이전트가 코드를 읽어 문서를 생성하고, 이후 변경을 수정안으로 준비할 수 있습니다.

GitHub는 두 곳에서 연결할 수 있습니다.

- **문서 프로젝트 만들기** 소스 단계의 **GitHub 연결** — 문서 생성의 근거가 될 저장소를 고릅니다.
- **도구와 스킬 → 커넥터 → GitHub**의 **연동** — 채팅에서 에이전트가 코드와 이슈·PR을 함께 참고하게 합니다. [커넥터 연결](/ko/guides/connectors)을 참고하세요.

## 연결 흐름

<Steps>
  <Step title="GitHub 연결 시작하기">
    문서 프로젝트 만들기 화면의 소스 단계에서 **GitHub 연결**을 선택합니다. 이 워크스페이스에서 저장소를 선택하려면 먼저 GitHub를 연결해야 합니다.

    <Screenshot name="project-wizard-source" alt="문서 프로젝트 만들기 소스 단계. 이 워크스페이스에서 저장소를 선택하려면 GitHub를 연결하세요 안내와 GitHub 연결 버튼" />
  </Step>
  <Step title="GitHub에서 접근 허용하기">
    GitHub 화면으로 이동하면 Specify가 읽을 계정과 저장소 범위를 선택하고 허용합니다.
  </Step>
  <Step title="저장소와 브랜치 선택하기">
    Specify로 돌아오면 **GitHub 계정**을 고르고 저장소 이름으로 검색해 선택한 뒤 브랜치를 고릅니다. 목록을 불러오지 못하면 `owner/repo` 형식으로 직접 입력할 수도 있습니다.
  </Step>
</Steps>

## 조직 저장소

조직 저장소는 GitHub 조직 관리자의 승인이 필요합니다.

1. 연결을 요청하면 GitHub가 조직 관리자에게 승인 요청을 보냅니다.
2. 조직 관리자가 GitHub에서 요청을 승인합니다.
3. 승인이 끝나면 Specify 화면에서 **다시 연결**을 눌러 완료합니다.

<Note>
  조직 관리자 승인을 기다리는 동안에는 해당 조직의 저장소가 목록에 나타나지 않습니다.
</Note>

## 채팅에서 GitHub 쓰기

커넥터로 GitHub를 연동하면 에이전트가 **저장소 코드·파일 내용**, **이슈·PR과 코멘트**, **커밋 이력**을 읽고, 코드 검색이나 이슈·PR 요약 같은 작업을 할 수 있습니다.

<Screenshot name="connector-github" alt="GitHub 커넥터 상세 창. 워크스페이스에 연동 버튼과 에이전트가 읽는 데이터, 맡길 수 있는 작업 목록이 보인다" caption="도구와 스킬 → 커넥터에서 GitHub를 누르면 열리는 상세 창입니다." />

## 여러 저장소 연결하기

하나의 문서 프로젝트에 소스를 여러 개 추가할 수 있습니다. 프로젝트 설정의 **저장소** 항목에서 문서의 근거로 사용할 저장소와 브랜치를 추가하거나 제거합니다. 각 소스에는 역할을 지정할 수 있습니다.

## push 시 실행

소스마다 **push 시 실행**을 켜면 해당 브랜치에 코드를 올릴 때도 문서 수정안을 준비합니다. 자세한 설정은 [자동화 상세 설정](/ko/guides/automation-settings)을 참고하세요.

## 문제 해결

| 증상 | 확인할 점 |
| --- | --- |
| 저장소를 불러오지 못함 | 잠시 후 다시 시도하거나 **직접 입력**으로 `owner/repo`를 입력합니다. |
| 사용할 수 있는 저장소가 없음 | 선택한 GitHub 계정에서 Specify 접근을 허용한 저장소가 있는지 확인합니다. |
| 사용할 수 있는 브랜치가 없음 | 저장소에 브랜치가 있는지, 접근 권한이 있는지 확인합니다. |
| 조직 저장소가 보이지 않음 | 조직 관리자의 승인이 끝났는지 확인한 뒤 다시 연결을 누릅니다. |