# GitHub 저장소 연결 — 푸시하면 자동 반영

> Source: https://wisdombase.ai/@help/features/github · Last updated: 2026-11-05

문서를 GitHub 저장소에서 마크다운으로 관리하고 있다면, 저장소를 브레인에 이어 두세요. **저장소에 푸시하면 문서 사이트와 AI 연결이 몇 초 안에 함께 갱신**돼요. 깃북(GitBook)의 Git Sync와 같은 방식이에요.

## 연결하기

1. 브레인 관리 → **GitHub** 탭을 열어요. 새 브레인을 만들 때는 마법사에서 **GitHub 저장소에서 만들기**를 골라도 돼요.
2. **저장소 주소**를 넣어요. `https://github.com/회사/문서-저장소` 처럼요. `…/tree/브랜치/폴더` 주소를 붙이면 브랜치와 문서 폴더까지 한 번에 읽어요.
3. **접근 권한**을 정해요. 방법은 둘이에요(공개 저장소는 둘 다 없이도 돼요).
   - **GitHub App으로 연결(권장)** — 「GitHub에 로그인해 저장소 고르기」를 누르면 조직에 위즈덤베이스 GitHub App을 설치하고 저장소를 고를 수 있어요. 담당자가 바뀌거나 퇴사해도 연결이 유지되고, 토큰처럼 만료되지 않아요. 웹훅도 앱이 알아서 관리해요. (이 서버에 앱이 설정돼 있을 때만 보여요.)
   - **개인 액세스 토큰** — GitHub → Settings → Developer settings → **Fine-grained tokens**에서 이 저장소만 골라 **Contents: Read-only** 권한으로 만들면 돼요. 웹훅까지 자동으로 등록하려면 **Webhooks: Read and write**도 켜요.
4. **미리보기**를 누르면 저장하지 않고 **어떤 페이지가 새로 생기고·바뀌고·지워지는지**, 본문이 어떻게 달라지는지 먼저 보여 드려요(기존 연결의 「전체 다시 읽기」 전에도 쓸 수 있어요).
5. **연결하고 첫 동기화 시작**을 누르면 바로 페이지가 만들어져요. 끝난 뒤에도 GitHub 탭에 **마지막 동기화에서 바뀐 페이지**가 쪽별로 남아요.

## 저장소가 이렇게 페이지가 돼요

- `.md` 파일 하나가 페이지 하나예요. 제목은 프런트매터의 `title`, 없으면 첫 `# 제목`, 그것도 없으면 파일 이름을 써요.
- 폴더가 위계가 돼요. 첫 단계 폴더는 **그룹**(문서 사이트 상단 메뉴), 그 안의 폴더는 **섹션**, 파일은 **페이지**예요. 폴더의 `README.md`는 그 그룹의 첫 페이지이자 이름이 돼요.
- 깃북식 `SUMMARY.md`가 있으면 그 목차를 그대로 따라요. 기본은 `## 파트`가 그룹, 들여쓴 항목이 섹션이에요. 연결 설정의 **목차의 ## 제목**에서 「하나의 그룹 아래 섹션으로」를 고르면 `##` 하나하나가 한 그룹 아래의 섹션이 돼요(들여쓴 항목은 부모 다음에 같은 섹션으로 펼쳐져요). 제목에 섞인 `<a href=…>` 같은 깃북 앵커는 걷어 내요. `.gitbook.yaml`의 `root` 설정도 읽어요.
- 이미 같은 **이름의 그룹**(상단 메뉴)이 있으면 새로 만들지 않고 이어받아요. 그래서 그 그룹의 주소(예: `/guide`)가 그대로 살아요. 이름이 달라서 이어받지 못한 옛 그룹에 숨김 페이지만 남으면, 그 옛 주소는 새 그룹으로 자동 이동(301)해요.
- 머리말에 `hidden: true`를 적은 파일은 **숨김 페이지**가 돼요(메뉴·검색에는 안 나오고 주소로만 열려요). 목차(`SUMMARY.md`)에 없어도 `hidden: true`라고 적혀 있으면 가져와요. `hidden` 줄이 없는 파일은 지금 숨김 상태를 건드리지 않아요.
- 페이지 안의 상대 링크는 우리 페이지 주소로, 이미지와 첨부 파일은 우리 저장소로 옮겨요. 저장소가 비공개여도 그림이 보여요.
- `CONTRIBUTING.md`, `LICENSE.md` 같은 저장소 관리용 파일과 `.`으로 시작하는 폴더는 건너뛰어요.

## 페이지 주소를 고정하려면

서비스 코드가 `/policies/terms`, `/pricing` 처럼 문서 주소를 직접 링크한다면, 파일 맨 위 머리말에 주소를 적어 두세요.

```
---
slug: policies/terms
---

# 이용약관
```

- 머리말 `slug`가 **그 페이지의 주소**가 돼요. 한 조각(`pricing`)도, 여러 조각(`admin-help/payments`)도 돼요. 제목을 고치거나 폴더를 옮겨도 주소는 그대로예요.
- 머리말이 없는 파일은 `그룹 주소/제목`으로 만들어요(기본). 연결 설정의 **페이지 주소 방식**에서 「파일 경로」를 고르면 머리말이 없는 파일도 폴더 경로로 만들어요 — `guide/install.md` → `/guide/install`, 폴더의 `README.md` → 폴더 주소(`/guide`). 머리말 `slug`가 있으면 항상 그쪽이 먼저예요.
- 같은 주소를 두 파일이 쓰면 앞선 파일이 이기고, 나머지는 기본 주소로 만든 뒤 동기화 결과에 알려 드려요. 사이트가 먼저 쓰는 `files`, `mcp` 같은 주소는 못 써요.
- **이미 있는 페이지와 이어 붙여요.** 가져오기로 만든 페이지처럼 같은 주소의 페이지가 이미 있으면 새로 만들지 않고 그 페이지를 파일과 묶어요(덮어쓰기 전 내용은 수정 기록에 남아요). 브랜치나 문서 폴더를 바꿔도 같은 파일 이름·제목의 페이지는 그대로 이어받아서 `-2` 사본이 생기지 않아요.
- **주소가 바뀌면 옛 주소가 자동으로 새 주소로 이동**해요(301). 편집기에서 주소를 직접 바꿀 때도 마찬가지예요. 제목 앵커(`#id-2026.07.16`처럼 깃북이 만들던 것)도 새 주소에서 그대로 열려요.
- 양방향으로 저장할 때 머리말의 다른 값(`slug`, `icon` 등)과 파일 첫 줄의 `# 제목`은 **원래 글자 그대로** 남아요. 위즈덤베이스에서 제목을 직접 바꿨을 때만 새 제목이 들어가요.

## 푸시하면 자동으로

- GitHub App으로 연결하면 앱이 모든 설치 저장소의 푸시를 알려 줘서 **저장소마다 웹훅을 만들 필요가 없어요**.
- 토큰을 넣고 연결하면 저장소에 **웹훅**을 자동으로 등록해요. 푸시가 오면 바뀐 파일만 골라 몇 초 안에 반영돼요.
- 토큰 없이 연결했으면 GitHub 탭에 나오는 **Payload URL과 Secret**으로 저장소 설정에 웹훅을 직접 추가하면 돼요. 안 추가해도 주기적으로 새 커밋을 확인하니 조금 늦게라도 반영돼요.
- 고쳐진 페이지는 **수정 기록**이 남아 편집 화면의 기록에서 이전 버전을 볼 수 있어요. 저장소에서 지운 파일의 페이지는 함께 지워져요(설정에서 끌 수 있어요).

## 양방향으로 쓰려면

기본은 **GitHub → 위즈덤베이스 한쪽**이에요. 저장소가 정본이라, 동기화되는 페이지를 여기서 고치면 다음 동기화 때 저장소 내용으로 되돌아가요(편집 화면 위에 안내가 보여요).

Git을 안 쓰는 동료도 편집기에서 고쳐야 한다면 **양방향**을 켜요. GitHub 탭 → 연결 설정에서 토큰에 **Contents: Read and write** 권한을 주고 「양방향」에 체크하면:

- 동기화되는 페이지를 편집기에서 저장하면 몇 초 안에 그 파일로 **커밋**돼요. 커밋 작성자에 고친 사람 이름이 남아요. **실제로 고친 블록(문단·표의 행·목록 항목)만** 바뀌고, 나머지 줄은 원문 그대로예요(편집기가 표 칸 폭을 다시 맞추거나 빈 줄을 줄이는 서식 차이는 수정으로 치지 않아요). 서식만 달라졌다면 커밋 자체를 만들지 않아요.
- 커밋 메시지는 기본이 「Update 제목 (이름 via Wisdombase)」예요. 편집기 위 칸에 **한 줄을 적고 저장**하면 그 말이 커밋 제목이 되고, 연결 설정의 **커밋 메시지 틀**(`{action}` `{title}` `{user}`)로 기본 모양을 바꿀 수도 있어요.
- 동기화 그룹 안에서 **새로 만든 페이지**는 새 파일이 되고(깃북식이면 `SUMMARY.md`에도 줄이 더해져요), **지운 페이지**는 파일이 지워져요. 새로 넣은 이미지는 `assets/` 폴더로 올라가요.
- 양쪽에서 **동시에 고치면 저장소가 이겨요**. 페이지는 저장소 내용으로 맞춰지고, 편집한 내용은 편집 화면의 **기록**에 남아 있어요. 저장한 사람에게는 **메일**로 알리고, 그 페이지 편집 화면에도 안내가 떠요.
- 페이지를 **숨기거나 다시 보이게** 하면 파일 머리말의 `hidden: true`로 올라가요. 페이지 순서 바꾸기·옮기기는 저장소에 올리지 않아요.

### 보호 브랜치를 쓰는 팀 — 풀 리퀘스트 모드

기준 브랜치(예: `main`)에 바로 쓸 수 없다면 연결 설정의 **저장소에 쓰는 방식**을 「작업 브랜치에 커밋하고 풀 리퀘스트 열기」로 바꾸세요.

- 편집기 저장은 작업 브랜치(`wisdombase/edits`)에 쌓이고, **풀 리퀘스트 하나**로 모여요. 합치면 기준 브랜치에 반영돼요.
- 합치기 전까지 그 페이지들은 **위즈덤베이스에서 고친 내용이 그대로** 유지돼요(동기화가 기준 브랜치 내용으로 덮어쓰지 않아요). 편집 화면에는 「아직 합쳐지지 않았어요」 안내와 풀 리퀘스트 링크가 보여요.
- 합치지 않고 **닫으면** 기준 브랜치 내용으로 돌아가고, 고친 내용은 수정 기록에 남아요(저장한 사람에게 알려 드려요).
- 토큰이나 앱에 **Pull requests: Read and write** 권한이 필요해요.

### 인증이 끊기거나 만료되면

- GitHub 탭에 토큰 **발급 계정과 만료일**이 보여요. 만료 **14일·7일·1일 전**과 만료·인증 실패 때 브레인 소유자에게 메일을 보내요. GitHub App으로 연결하면 만료가 없어요.
- 인증이 끊긴 동안 편집기에서 저장하면 「지금은 저장소에 반영되지 않아요」라고 알려 드리고, 그 내용은 **보류**해 둬요. 새 토큰을 넣거나 앱으로 다시 연결하면 **보류된 저장이 저장소에 올라가요**. 그 사이 저장소의 같은 파일이 바뀌었다면 저장소가 이기고 편집 내용은 수정 기록에 남아요.
- 연결을 끊을 때 토큰이 이미 만료돼 있으면 저장소에 등록된 웹훅을 지우지 못해요. 안내가 뜨면 저장소 Settings → Webhooks에서 직접 지워 주세요(남아 있어도 이 브레인은 그 알림을 받지 않아요).

## 알아 두세요

- 저장소 밖에서 직접 만든 페이지는 동기화가 건드리지 않아요. 저장소 문서와 직접 쓴 페이지를 한 브레인에서 섞어 쓸 수 있어요. 「지워진 파일의 페이지도 함께 지우기」를 켜도 동기화로 만든(또는 이어 붙인) 페이지만 지워요. 단, 같은 주소라서 파일과 이어 붙은 페이지는 이때부터 동기화 대상이에요.
- 브레인 하나에는 저장소 하나만 이을 수 있어요. 저장소 안 일부만 쓰려면 **문서 폴더**를 지정하세요. 폴더 칸을 비우고 저장하면 저장소 전체가 돼요.
- 웹훅 Secret은 화면에서 가려져 있어요. 「보기」를 눌렀을 때만 나타나고, 복사 버튼은 가린 채로도 써요.
- 한 번에 가져오는 마크다운은 2,000개, 저장소는 100MB까지예요. 더 크면 **문서 폴더**를 지정해 범위를 줄여 주세요.
- 연결을 끊어도 페이지는 그대로 남아요.