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

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

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

## 연결하기

1. 브레인 관리 → **GitHub** 탭을 열어요. 새 브레인을 만들 때는 마법사에서 **GitHub 저장소에서 만들기**를 골라도 돼요.
2. **저장소 주소**를 넣어요. `https://github.com/회사/문서-저장소` 처럼요. `…/tree/브랜치/폴더` 주소를 붙이면 브랜치와 문서 폴더까지 한 번에 읽어요.
3. 비공개 저장소라면 **액세스 토큰**을 넣어요. GitHub → Settings → Developer settings → **Fine-grained tokens**에서 이 저장소만 골라 **Contents: Read-only** 권한으로 만들면 돼요. 웹훅까지 자동으로 등록하려면 **Webhooks: Read and write**도 켜요. 공개 저장소는 토큰 없이도 돼요.
4. **연결하고 첫 동기화 시작**을 누르면 바로 페이지가 만들어져요.

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

- `.md` 파일 하나가 페이지 하나예요. 제목은 프런트매터의 `title`, 없으면 첫 `# 제목`, 그것도 없으면 파일 이름을 써요.
- 폴더가 위계가 돼요. 첫 단계 폴더는 **그룹**(문서 사이트 상단 메뉴), 그 안의 폴더는 **섹션**, 파일은 **페이지**예요. 폴더의 `README.md`는 그 그룹의 첫 페이지이자 이름이 돼요.
- 깃북식 `SUMMARY.md`가 있으면 그 목차를 그대로 따라요. `## 파트`가 그룹, 들여쓴 항목이 섹션이 돼요. `.gitbook.yaml`의 `root` 설정도 읽어요.
- 페이지 안의 상대 링크는 우리 페이지 주소로, 이미지와 첨부 파일은 우리 저장소로 옮겨요. 저장소가 비공개여도 그림이 보여요.
- `CONTRIBUTING.md`, `LICENSE.md` 같은 저장소 관리용 파일과 `.`으로 시작하는 폴더는 건너뛰어요.

## 푸시하면 자동으로

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

## 양방향으로 쓰려면

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

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

- 동기화되는 페이지를 편집기에서 저장하면 몇 초 안에 그 파일로 **커밋**돼요. 커밋 작성자에 고친 사람 이름이 남아요.
- 동기화 그룹 안에서 **새로 만든 페이지**는 새 파일이 되고(깃북식이면 `SUMMARY.md`에도 줄이 더해져요), **지운 페이지**는 파일이 지워져요. 새로 넣은 이미지는 `assets/` 폴더로 올라가요.
- 양쪽에서 **동시에 고치면 저장소가 이겨요**. 페이지는 저장소 내용으로 맞춰지고, 편집한 내용은 편집 화면의 **기록**에 남아 있어요.
- 페이지 순서 바꾸기·옮기기·숨기기는 저장소에 올리지 않아요.

## 알아 두세요

- 저장소 밖에서 직접 만든 페이지는 동기화가 건드리지 않아요. 저장소 문서와 직접 쓴 페이지를 한 브레인에서 섞어 쓸 수 있어요.
- 한 번에 가져오는 마크다운은 2,000개, 저장소는 100MB까지예요. 더 크면 **문서 폴더**를 지정해 범위를 줄여 주세요.
- 연결을 끊어도 페이지는 그대로 남아요.