GitHub Sync 설정
제 38 장: GitHub Sync 설정
GitHub Sync는 SeaMeet 워크스페이스를 자체 GitHub 저장소에 있는 비공개, 버전 관리되는 Markdown 트리로 변환합니다. 메모를 편집하거나, 녹음 이름을 변경하거나, wiki 페이지를 조정할 때마다 SeaMeet은 백그라운드에서 조용히 변경 사항을 커밋하고 GitHub에 푸시합니다. 다른 노트북에서 SeaMeet을 열면 처음 시작할 때 메모가 끌어내려집니다 — 중간에 Dropbox도 없고, 루프에 Seasalt 서버도 없습니다. 저장소는 사용자의 것이며, 데이터도 사용자의 것이며, 원할 때 언제든지 github.com에서 직접 탐색할 수 있습니다.
모델은 간단합니다: GitHub 저장소가 저장소입니다. SeaMeet은 동기화 서비스를 실행하지 않습니다. 계정에 작은 GitHub App을 설치하고, 사용자별 OAuth 토큰을 받아 해당 토큰을 사용해 Git 커밋을 직접 푸시하고 풀합니다. 저장소가 GitHub의 무료 등급 — 무제한 비공개 저장소 제공 — 이므로 동기화는 사실상 무료입니다. 그리고 각 SeaMeet 워크스페이스가 자체 저장소이기 때문에, 업무용과 개인용 워크스페이스를 완전히 분리할 수 있습니다.
장의 목표
이 장을 읽고 나면 다음을 할 수 있습니다:
- 계정 또는 조직에 SeaMeet GitHub App 설치
- OAuth를 통해 SeaMeet을 승인하고 비공개 동기화 저장소를 생성하도록 허용
- 동기화 상태 표시줄을 읽고 동기화 상태 머신의 각 상태 이해
- OAuth가 백그라운드에서 자동 갱신되었을 때와 수동으로 재승인해야 할 때 인식
- 두 기기에서 동일한 메모가 편집된 경우 동기화 충돌 해결
- 동기화 설정 패널 조정 (자동 동기화, 동기화 간격, 시작 시 동기화)
- 가장 일반적인 실패 모드 문제 해결
전제 조건
시작하기 전에 다음을 갖추고 있는지 확인하세요:
- GitHub 계정 — 무료 등급으로 충분합니다. GitHub Pro는 필요 없습니다
- 활성 동기 화 권한 — BYOK Pro 및 Sync Pro 등급에 포함됩니다. 청구 등급에 동기화가 포함되어 있지 않은 경우, 동기화 설정 화면에 "동기화를 활성화하려면 구독하세요" 배너가 표시됩니다. 플랜 세부 정보는 제 35 장: 구독 및 결제를 참조하세요.
- SeaMeet에서 열려 있는 워크스페이스 — 동기화는 앱 전체가 아닌 활성 워크스페이스에 연결됩니다. 여러 워크스페이스가 있는 경우 각각이 자체 GitHub 저장소입니다.
- 작동하는 인터넷 연결 — 설정 흐름은 기본 브라우저에서 GitHub를 엽니다
워크스페이스당 하나의 저장소. SeaMeet은 연결하는 각 워크스페이스마다 별도의 비공개 저장소를 생성합니다. 이렇게 하면 업무 메모와 개인 메모를 깔끔하게 분리할 수 있고, 하나를 끊더라도 다른 것을 건드리지 않을 수 있습니다.
단계별 설정
처음 설정에는 약 90초가 걸립니다: GitHub에서 SeaMeet 승인, 저장소 생성 허용, 초기 업로드 대기, 완료.
1 단계: 동기화 설정 열기
- 설정 톱니바퀴 아이콘 클릭
- 왼쪽 레일에서 Sync 탭 열기
- "Sync with GitHub" 헤더 카드가 보입니다
Sync 탭이 보이지 않으면 구독 등급에 동기화가 포함되어 있지 않은 것입니다 — 업그레이드는 제 35 장을 참조하세요.
*"Back up your notes to a private GitHub repo with BYOK Pro"*라는 배너가 표시되면 무료 계정입니다. 배너를 클릭하여 유료 화면을 열거나, 구독할 때까지 본 장의 나머지 부분을 건너뛰세요.
2 단계: "Set Up GitHub Sync" 클릭
동기화 설정 빈 상태는 세 개의 혜택 타일 ("Free & private", "Effectively unlimited", "One repo per workspace")과 하단에 기본 Set Up GitHub Sync 버튼을 보여줍니다.
클릭하세요. 기본 브라우저가 GitHub 승인 페이지를 엽니다.
3 단계: SeaMeet GitHub App 설치 (일회성)
처음으로 SeaMeet을 승인할 때 GitHub는 계정에 SeaMeet GitHub App을 설치하도록 요청합니다. 이는 GitHub 계정당 (또는 조직 소유 저장소에 동기화하려는 경우 조직당) 일회성 단계입니다.
GitHub 설치 페이지에서:
- SeaMeet이 쓰기 작업을 할 계정 또는 조직 선택
- "All repositories" 또는 "Only select repositories" 중 하나 선택 — SeaMeet App은 동기화 저장소를 사용자 대신 생성하기 위해
contents: write및administration: write권한이 필요합니다 - Install & Authorize 클릭
GitHub는 SeaMeet으로 다시 돌아갑니다. 동기화 설정 패널에 이제 다음이 표시됩니다:
┌──────────────────────────────────────────────────────┐
│ ✓ 승인됨 │
│ ⟳ 저장소를 생성하고 업로드 중... │
└──────────────────────────────────────────────────────┘
왜 단순 OAuth 토큰이 아닌 GitHub App인가? GitHub Apps는 저장소별 세분화된 권한과 회전하는 리프레시 토큰을 가지고 있습니다. SeaMeet은 사용자가 명시적으로 선택한 저장소에만 쓰기 액세스 권한을 가지며, OAuth 액세스 토큰은 8시간마다 만료됩니다 — 누출되더라도 창은 작습니다. (SeaMeet이 어떻게 이것을 보이지 않게 유지하는지에 대해서는 아래의 OAuth 자동 갱신 섹션을 참조하세요.)
4 단계: 저장소 생성 (자동)
SeaMeet은 이제 사용자 대신 GitHub API를 호출하고 다음을 수행합니다:
- 워크스페이스 이름을 딴 비공개 저장소 생성 (예:
seameet-work-notes) - 워크스페이스 폴더 내에 로컬 Git 저장소가 아직 없는 경우 초기화
git init실행, 오디오/비디오/스크린샷 파일을 제외하는.gitignore작성, 초기 커밋 수행- 새 GitHub 저장소를
origin으로 추가 - 초기 커밋 푸시
사이드바 하단의 상태 표시줄이 다음과 같이 전환되는 것을 볼 수 있습니다:
저장소를 생성 중... → 동기화 중... → 동기화됨 · 방금 전
이게 다입니다. 이제 워크스페이스가 GitHub로 백업됩니다.
5 단계: 첫 번째 동기화가 자동으로 실행됩니다
이제부터 SeaMeet은 저장되지 않은 변경 사항이 있을 때마다 기본적으로 5분마다 자동 커밋하고, 각 커밋 직후 GitHub로 푸시합니다. 다음 SeaMeet 실행 시 앱은 편집을 시작하기 전에 GitHub에서 풀합니다 — 그래서 다른 기기에서 변경한 사항이 앱이 열리는 순간 나타납니다.
동기화 상태 머신
SeaMeet의 SyncManager는 작은 상태 머신을 실행하고 현재 상태를 렌더러에 브로드캐스트합니다. 사이드바의 SyncStatusBar와 동기화 설정 패널 모두 이 상태에서 읽습니다. 상태를 이해하면 UI를 정확하게 읽는 데 도움이 됩니다.
┌─────────────┐
│ idle │ ◄──────┐
└──────┬──────┘ │
│ 파일 변경 │
▼ │
┌─────────────┐ │
┌────►│ pending │ │
│ └──────┬──────┘ │
파일 │ │ 커밋 타이머 │
변경 │ ▼ │
│ ┌─────────────┐ │
│ │ committing │ │
│ └──────┬──────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ pushing │ │
│ └──────┬──────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ synced │── 5s ──┘
│ └─────────────┘
│
│ ┌─────────────┐
├─────┤ pulling │ (시작 시 또는 푸시 거부됨)
│ └─────────────┘
│
│ ┌─────────────┐
├─────┤ conflict │ → 사용자 해결 → syncing → synced
│ └─────────────┘
│
│ ┌─────────────┐
├─────┤ offline │ → 네트워크 복구 → 재시도
│ └─────────────┘
│
│ ┌─────────────┐
├─────┤ timeout │ → 사용자가 "재시도" 클릭
│ └─────────────┘
│
│ ┌────────────────┐
└─────┤ token-expired │ → 재승인 카드
└────────────────┘
각 상태가 UI에서 의미하는 바는 다음과 같습니다:
| 상태 | 상태 표시줄 레이블 | 의미 |
|---|---|---|
| idle | "Synced · 2 min ago" | 대기 중인 것 없음, 마지막 커밋이 깔끔했음 |
| pending | "Pending..." | 저장되지 않은 변경 사항 있음; 커밋 타이머가 다음 간격에 실행됨 |
| committing | "Syncing..." | Git 커밋이 로컬에서 진행 중 |
| pushing | "Pushing..." | 로컬 커밋 완료; GitHub로 푸시 중 |
| pulling | "Pulling..." | 시작 동기화이거나 푸시가 거부되어 먼저 풀하고 있음 |
| syncing | "Syncing..." | 충돌 해결 후 rebase 완료 |
| synced | "Synced · just now" | 방금 완료된 성공; 5초 동안 표시된 후 idle로 돌아감 |
| conflict | "Sync conflict" | 로컬과 원격 모두 같은 파일을 편집함. UI는 충돌 해결 흐름을 표시함. |
| error | "Sync error" | 네트워크 외, 충돌 외 실패 (예: git 실패). 지수 백오프로 최대 5회 자동 재시도. |
| offline | "Offline" | 네트워크 연결 불가. 다음 파일 변경 시 또는 60초 후 재시도. |
| timeout | "Sync timed out" | git 명령이 60초 이상 걸림 (아래 동기화 타임아웃 보호 참조) |
| token-expired | "Re-authorize" | OAuth 갱신 실패, 사용자가 수동으로 재승인해야 함 |
| installing-app | "Installing GitHub App..." | 사용자가 브라우저에서 GitHub App 설치 단계를 완료하기를 기다리는 중 |
| creating-repo | "Creating repository..." | 설정 흐름이 GitHub 저장소를 생성하고 초기 커밋을 푸시하는 중 |
상태 표시줄에 스피너가 표시되면 정상적인 백그라운드 활동입니다. 호박색 또는 빨간색인 경우, 아래 문제 해결 섹션을 참조하세요.
OAuth 자동 갱신
GitHub Apps는 8시간마다 만료되는 사용자 액세스 토큰과 6개월 동안 유효한 리프레시 토큰을 발급합니다. SeaMeet은 이를 사용자를 위해 관리하므로 거의 생각할 필요가 없습니다.
작동 방식:
- SeaMeet이 푸시 또는 풀을 시작하려고 할 때,
SyncManager._refreshTokenIfNeeded()는 현재 토큰이 다음 5분 이내에 만료되는지 확인합니다. - 그렇다면 SeaMeet은 저장된 리프레시 토큰으로 GitHub의
/login/oauth/access_token엔드포인트를 호출합니다. GitHub는 새 액세스 토큰을 반환하고 리프레시 토큰을 회전합니다. SeaMeet은 둘 다 디스크의 암호화된 토큰 파일에 다시 씁니다. - 그런 다음 Git 명령은 새로 갱신된 토큰으로 실행됩니다. 화면에 아무것도 표시되지 않습니다 — 전체 갱신은 1초 미만이 걸립니다.
일시적 실패 처리: 네트워크가 불안정하거나 GitHub가 5xx (REFRESH_NETWORK_ERROR)를 반환하여 갱신 호출이 실패하면, SeaMeet은 기존 토큰을 버리지 않습니다. 대신 동기화가 offline 상태로 들어가고 나중에 다시 시도합니다. 기존 토큰이 몇 분 동안 더 유효할 수 있기 때문에 중요합니다 — 일시적인 네트워크 끊김에서 폐기하면 동기화에서 불필요하게 로그아웃됩니다.
동시 갱신 통합: GitHub는 사용할 때마다 리프레시 토큰을 회전하므로, 두 개의 동시 갱신은 경쟁하고 하나가 다른 하나를 무효화합니다. SeaMeet은 동시 갱신 호출을 단일 진행 중인 Promise (_refreshPromise)로 축소하여, 시작 동기화와 재시도가 포함된 푸시가 회전하는 토큰을 두고 다투지 않도록 합니다.
갱신이 정말로 실패할 때: GitHub가 REFRESH_TOKEN_EXPIRED를 반환하면 — 6개월 리프레시 토큰이 만료되었거나 취소되었음을 의미합니다 — SeaMeet은 다음을 수행합니다:
- 디스크에서 암호화된 토큰 파일 삭제
token-expired종료 상태에 진입- 동기화 설정에 호박색 카드 표시:
┌──────────────────────────────────────────────────────┐
│ ⚠ GitHub 승인이 만료되었습니다. 동기화를 재개하려면 │
│ 재승인해 주세요. │
│ │
│ [ ↻ GitHub 재승인 ] │
└──────────────────────────────────────────────────────┘
GitHub 재승인을 클릭하세요. OAuth 흐름을 통해 다시 보내집니다 — 그러나 GitHub App이 이미 설치되어 있기 때문에, 확인을 위해 한 번 클릭하면 약 10초 안에 완료됩니다. SeaMeet은 그런 다음 다음 푸시 전에 로컬 git config에서 오래된 토큰을 제거합니다 (오래된 토큰이 origin의 URL에 포함되어 있을 수 있음). 이렇게 하면 죽은 자격 증명에서 반복되지 않습니다.
동기화 타임아웃 보호
전송 중간에 네트워크가 조용해지면 Git 명령은 영원히 멈출 수 있습니다 — TCP 소켓이 오류를 발생시키지 않고 반쯤 열린 상태로 있을 수 있습니다. SeaMeet은 모든 Git 푸시 및 풀을 60초 AbortController 타임아웃으로 감쌉니다.
푸시 또는 풀이 60초 내에 완료되지 않으면, SeaMeet은 다음을 수행합니다:
- git 서브프로세스 중단
timeout상태에 진입- 동기화 설정에 호박색 카드 표시:
┌──────────────────────────────────────────────────────┐
│ ⚠ 동기화 시간이 초과되었습니다. 네트워크 문제 또는 │
│ GitHub 승인 만료로 인한 것일 수 있습니다. │
│ │
│ [ ↻ 동기화 재시도 ] [ GitHub 재승인 ] │
└──────────────────────────────────────────────────────┘
동기화 재시도는 commitNow를 다시 실행합니다. 네트워크가 잠시 끊겼다고 생각되면 이 버튼을 클릭하는 것이 맞습니다. GitHub 재승인은 OAuth 흐름을 다시 실행합니다; 타임아웃이 계속 반복되면 이 버튼을 클릭하세요. 이는 일반적으로 네트워크가 아니라 토큰이 문제임을 의미합니다.
아무것도 클릭하지 않더라도 상태는 약 30초 후에 자동으로 idle로 돌아갑니다 — 동기화는 다음 파일 변경 시 재시도됩니다.
충돌 해결
마지막 동기화 이후 같은 파일이 두 기기에서 편집되었을 때 충돌이 발생합니다. 예: 노트북에서 meetings/2026-06-03-standup.md에 단락을 작성한 다음, 나중에 친구의 기기에서 같은 단락을 편집했습니다. 두 번째 기기가 푸시할 때 GitHub는 기록이 분기되어 푸시를 거부합니다.
SeaMeet은 다음과 같이 처리합니다:
- rebase로 원격 변경 사항 풀
- 병합 충돌 마커 감지
conflict상태에 진입- 사이드바 상태 표시줄 (클릭 가능해짐) 및 동기화 설정 충돌 패널에서 충돌 표시
충돌 해결 모달
동기화가 conflict 상태일 때 상태 표시줄을 클릭하면 충돌 해결 모달이 열립니다:
┌──────────────────────────────────────────────────────────┐
│ ⚠ 동기화 충돌 1 / 2 [×] │
├──────────────────────────────────────────────────────────┤
│ │
│ "2026-06-03-standup.md"가 다른 기기에서 변경되었습니다. │
│ │
│ ┌────────────────────────┐ ┌────────────────────────┐ │
│ │ ✎ 수동으로 편집 │ │ ✦ Agent 병합 │ │
│ └────────────────────────┘ └────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────┘
두 가지 옵션이 있습니다:
수동으로 편집 — 시스템의 기본 편집기에서 충돌 파일을 엽니다. Git의 표준 <<<<<<< / ======= / >>>>>>> 마커가 제자리에 있습니다. 파일을 편집하여 해결하고, 저장한 다음, SeaMeet으로 돌아와 완료를 클릭합니다. SeaMeet은 해결된 파일을 스테이징하고 rebase를 계속합니다.
Agent 병합 (BYOK Pro 전용, 구성된 AI 에이전트 필요) — 두 버전을 구성된 AI 에이전트 (GitHub Copilot 또는 Claude Code, 제 36 장: BYOK 설정 가이드 참조)에 보내고 양쪽의 의도를 유지하는 병합된 버전을 생성하도록 요청합니다. 에이전트의 출력은 자동으로 스테이징되며, rebase가 완료되는 동안 "동기화 완료 중..." 스피너가 표시됩니다.
한 번에 여러 충돌이 있는 경우, 모달에 카운터 (1 / 2, 2 / 2)와 동기화 설정 충돌 패널에 화살표가 표시되어 한 번에 하나씩 단계별로 이동할 수 있습니다.
"Keep mine" / "Keep theirs" / "Keep both" 옵션은 수동 편집기 안에 있을 때 자연스러운 선택지로 나타납니다: 마커 사이에 사용자 버전의 텍스트만 남기거나, 원격 버전의 텍스트만 남기거나, 둘을 교차하여 남길 수 있습니다. Agent 병합 버튼은 사실상 "양쪽을 지능적으로 유지"합니다.
실수를 하면 어떻게 될까? 동기화 충돌은 비파괴적입니다. Git은 인덱스에 원래 "ours"와 "theirs" 내용을 보관하며,
getConflictVersions(filePath)는 해결 중 언제든지 둘 중 하나를 가져올 수 있습니다. 실수로 작업을 잃지 않습니다.
동기화 설정 패널
연결되면 동기화 설정 (설정 → Sync)은 모든 것을 한 곳에 모아놓은 단일 화면을 제공합니다:
┌─────────────────────────────────────────────────────────────┐
│ ✓ 동기화 및 백업 │
│ 메모와 wiki는 GitHub로 자동으로 동기화됩니다. │
│ 오디오 녹음, 비디오 녹음 및 스크린샷은 │
│ 동기화되지 않습니다. │
├─────────────────────────────────────────────────────────────┤
│ ⓘ https://github.com/you/seameet-work-notes │
│ 🕒 마지막 동기화: 4분 전 │
├─────────────────────────────────────────────────────────────┤
│ 자동 동기화 [ 켜기 ◉ ] │
│ 동기화 간격 [ 5 분 ▾ ] │
│ 브랜치 main │
│ 마지막 동기화 4분 전 │
├─────────────────────────────────────────────────────────────┤
│ 변경 시 자동 동기화 [ 켜기 ◉ ] │
│ 시작 시 동기화 [ 켜기 ◉ ] │
├─────────────────────────────────────────────────────────────┤
│ [ ⤓ 지금 동기화 ] │
├─────────────────────────────────────────────────────────────┤
│ [ ↗ GitHub에서 보기 ] [ 연결 해제 ] │
└─────────────────────────────────────────────────────────────┘
위에서 아래로 컨트롤:
- 자동 동기화 — 백그라운드 커밋 타이머의 마스터 토글. 꺼짐은 SeaMeet이 지금 동기화를 클릭할 때만 커밋함을 의미합니다.
- 동기화 간격 — 커밋 타이머가 실행되는 빈도. 선택지는 1 / 5 / 10 / 30분입니다. 기본값은 5분입니다. 1분 간격은 활발한 메모 작성에 적합하고, 30분은 커밋을 일괄 처리하는 것을 선호하는 저편집 워크스페이스에 적합합니다.
- 브랜치 — SeaMeet이 동기화하는 Git 브랜치. 거의 항상
main입니다. UI에서 읽기 전용입니다. - 마지막 동기화 — 마지막으로 성공한 푸시의 상대 타임스탬프.
- 변경 시 자동 동기화 — 켜져 있으면 각 로컬 커밋 직후 푸시가 발생합니다 (일반적인 경우). 꺼져 있으면 SeaMeet은 로컬에 커밋하지만 지금 동기화를 클릭할 때만 푸시합니다. 푸시를 일괄 처리하려는 경우 (예: 종량제 연결) 유용합니다.
- 시작 시 동기화 — 켜져 있으면 SeaMeet은 앱이 시작되는 순간 GitHub에서 풀합니다. 매우 느린 연결이 아닌 한 권장됩니다.
- 지금 동기화 — 즉시 커밋 및 푸시 사이클을 강제 실행. 타이머를 기다리지 않습니다. 노트북을 닫기 전에 유용합니다.
- GitHub에서 보기 — 브라우저에서 저장소를 엽니다.
- 연결 해제 — 저장된 OAuth 토큰을 지우고, 암호화된 토큰 파일을 삭제하고, 로컬 Git 저장소에서
origin을 제거합니다. 로컬 Markdown 파일과 Git 기록은 그대로 유지됩니다 — GitHub로의 링크만 끊어집니다.
동기화되는 항목 (및 동기화되지 않는 항목)
이는 파트 인덱스에 문서화되어 있지만, 여기서 다시 언급할 가치가 있습니다:
| 동기화됨 | 동기화 안 됨 |
|---|---|
메모 (.md 파일) | 오디오 녹음 (.webm, .mp3) |
Wiki 페이지 (.md 파일) | 비디오 녹음 (.webm, .mp4) |
| 녹음 매니페스트 (메타데이터 JSON) | 스크린샷 (.png, .jpg) |
| AI 요약 및 전사본 | 캐시된 AI 생성물 |
| Wikilink 그래프 | 앱 설정 |
.gitignore | 편집기 임시 상태 |
SeaMeet이 작성하는 .gitignore는 모든 대용량 바이너리 범주를 제외합니다. 이는 의도적입니다: GitHub의 무료 비공개 저장소는 1GB로 제한되며, 30분 비디오는 그것만으로도 다 소비합니다. SeaMeet은 미디어를 로컬 디스크에 보관하고 경량 Markdown만 동기화합니다.
전체 미디어 동기화가 필요하다면, 이는 Sync Pro 등급입니다 — 제 35 장을 참조하세요.
문제 해결
Set Up GitHub Sync를 클릭한 직후 "승인 실패"
원인 및 해결:
- 팝업 차단기 — 브라우저 창이 열리지 않았다면 OS 또는 브라우저가 시작을 차단했을 수 있습니다. Set Up GitHub Sync를 다시 클릭하고 모든 팝업 프롬프트를 확인하세요.
- GitHub App 권한을 거부했음 — 다시 흐름을 진행하고
contents: write+administration: write범위를 수락하세요.administration: write가 없으면 SeaMeet은 사용자를 위해 저장소를 생성할 수 없습니다. - 상태 불일치 오류 — 같은 OAuth 흐름에서 경쟁할 수 있는 다른 SeaMeet 창을 닫고 다시 시도하세요.
설정 중 "Repo permissions" 오류
오류는 *"GitHub App has 'contents: read' permission, but needs 'contents: write'."*와 같은 내용입니다. 이는 이전 버전의 App을 설치했음을 의미합니다.
해결:
- github.com/settings/installations을 엽니다
- 목록에서 SeaMeet을 찾아 Configure를 클릭합니다
- Repository permissions에서 Contents 및 Administration을 Read and write로 변경합니다
- 저장한 다음, 앱을 제거하고 다시 설치하세요 — GitHub는 다시 설치할 때만 새 권한을 적용합니다
- SeaMeet에서 Set Up GitHub Sync를 다시 실행하세요
"GitHub에 도달할 수 없음" / 동기화가 "Offline"에 멈춤
네트워크 장애입니다. SeaMeet은 다음 경우 자동으로 재시도합니다:
- 파일을 변경할 때 (즉시 재시도 시도 트리거)
- 마지막 재시도로부터 60초 경과
네트워크가 복구되었는데도 몇 분 후에 동기화가 여전히 Offline으로 표시되면:
- 지금 동기화를 클릭하여 재시도 강제
- 그것이 시간 초과되면: 방화벽이 github.com을 차단하지 않는지 확인
- 마지막 수단으로, SeaMeet 재시작 — 시작 동기화가 시작 시 실행됩니다
동기화가 "Pending"에 멈춤
이는 일반적으로 자동 커밋 타이머가 아직 실행되지 않았음을 의미합니다. 기본적으로 5분마다 실행됩니다. 기다리고 싶지 않다면? 지금 동기화를 클릭하세요.
지금 동기화가 동기화를 Pending 이상으로 이동하지 않으면 다음을 확인하세요:
- 동기화가 포함된 청구 등급에 있습니까? 동기화 설정을 열어 보세요 — 구독 배너가 보이면 권한 계층에서 동기화가 비활성화되어 있습니다.
- Markdown 트리 외부에 커밋되지 않은 변경 사항이 있습니까? 자동 커밋 타이머는
_pendingChanges가 비어 있지 않을 때만 실행됩니다.
"token-expired 카드가 보입니다"
이는 OAuth 갱신 라이프 사이클의 예상되는 끝입니다 — 6개월 리프레시 토큰이 만료되었거나, GitHub App을 취소했거나, GitHub 비밀번호를 변경했습니다 (이는 모든 OAuth 토큰을 무효화합니다).
해결: 카드에서 GitHub 재승인을 클릭하세요. 흐름은 초기 설정과 동일하지만 GitHub App 설치 단계를 건너뜁니다 (이미 설치되어 있음). 약 10초가 걸립니다.
충돌 해결 패널이 닫히지 않음
패널은 목록의 모든 충돌이 해결되었을 때만 닫힙니다. 카운터 (1 / 3)가 보이면 동기화 설정 충돌 패널의 화살표를 사용하여 나머지 파일을 단계별로 이동하세요. 각 파일에는 명시적인 해결 (수동 편집 + 완료, 또는 Agent 병합)이 필요합니다.
패널이 충돌이 있다고 주장하지만 파일에 마커가 보이지 않으면 지금 동기화를 클릭하세요 — 오래된 conflict 상태는 다음 성공적인 동기화 시도에서 지워집니다.
"푸시 거부" 루프
동기화가 pushing과 pulling 사이를 반복적으로 번갈아 가면 GitHub가 푸시를 거부하고 있으며 원격이 계속 앞으로 나아가고 있기 때문입니다. 다음과 같은 경우 발생할 수 있습니다:
- 다른 SeaMeet 인스턴스가 같은 저장소에 대해 실행 중이며 이것이 따라잡을 수 있는 속도보다 빠르게 푸시하고 있음 — 다른 인스턴스를 닫으세요.
- 누군가 (또는 어떤 도구가) SeaMeet 외부에서 GitHub 저장소에 커밋하고 있음 — 로컬 복제본이 따라잡을 때까지 외부 도구를 일시 중지하세요.
보안 노트
OAuth 토큰이 저장되는 위치: Electron의 safeStorage API를 통해 OS 키체인에 저장됩니다. Windows에서는 DPAPI, macOS에서는 Keychain Services, Linux에서는 libsecret입니다. 암호화된 blob은 파일 모드 0o600으로 <userData>/github-token.enc에 작성됩니다. 파일에는 액세스 토큰, 리프레시 토큰, 만료 타임스탬프, GitHub App의 클라이언트 ID, 클라이언트 시크릿, slug가 포함됩니다.
argv에 저장되지 않는 것: OAuth 토큰은 -c http.extraHeader=... 인수로 git에 전달되지 않습니다. argv는 ps aux를 통해 다른 사용자에게 표시되기 때문입니다. 대신 Authorization 헤더는 프로세스에 비공개인 GIT_CONFIG_PARAMETERS 환경 변수를 통해 주입됩니다. 같은 기기의 다른 사용자는 토큰을 볼 수 없습니다.
저장소의 디스크에 결국 남는 것: 일반 Markdown 파일입 니다. 토큰, 비밀, 자격 증명이 없습니다. .gitignore는 미디어 파일을 제외하지만, 메모 본문에 비밀을 붙여넣는 것은 여전히 피해야 합니다 — 그것은 동기화될 것입니다.
액세스 취소: 저장소에 대한 SeaMeet의 액세스를 즉시 차단하려면 github.com/settings/installations에서 SeaMeet GitHub App을 제거하세요. 다음 동기화 시도는 token-expired로 실패하고 SeaMeet은 로컬 토큰을 지웁니다. 로컬 메모는 영향을 받지 않습니다.
빠른 참조
┌─────────────────────────────────────────────────────────────┐
│ GITHUB SYNC │
│ 빠른 참조 │
├─────────────────────────────────────────────────────────────┤
│ 동기화 설정 열기 │ 설정 → Sync │
│ 처음 설정 │ "Set Up GitHub Sync" 클릭 │
│ 필수 범위 │ contents: write, admin: write │
│ 저장소 명명 │ 워크스페이스당 하나의 비공개 저장소 │
├─────────────────────────────────────────────────────────────┤
│ 기본 동기화 간격 │ 5분 (1 / 5 / 10 / 30) │
│ 동기화 강제 │ "Sync Now" 버튼 │
│ 푸시 시 자동 동기화 │ 켜기 (동기화 설정에서 토글) │
│ 시작 시 동기화 │ 켜기 (동기화 설정에서 토글) │
├─────────────────────────────────────────────────────────────┤
│ OAuth 갱신 마진 │ 만료 5분 전 │
│ Git 명령 타임아웃 │ 60초 (AbortController) │
│ 자동 재시도 한도 │ 5회 시도, 지수 백오프 │
│ 토큰 저장 │ OS 키체인 (safeStorage) │
├─────────────────────────────────────────────────────────────┤
│ 충돌 UI │ 충돌 시 상태 표시줄 클릭 │
│ 수동 해결 │ 마커 편집 → 완료 │
│ Agent 병합 │ BYOK Pro + 구성된 AI 에이전트 │
├─────────────────────────────────────────────────────────────┤
│ 연결 해제 │ 동기화 설정 → 연결 해제 │
│ GitHub에서 취소 │ github.com/settings/installations │
│ 저장소 보기 │ "View on GitHub" 링크 │
└─────────────────────────────────────────────────────────────┘
Last updated: 2026-06-04
← 제 37 장: GitHub Copilot 공급자 | (매뉴얼 끝 — 인덱스로 돌아가기)
Published: