Інтеграція з Git

Двонаправлена синхронізація git у DocPlatform дозволяє вашій команді працювати так, як їм зручно. Технічні письменники використовують веб-редактор. Розробники відправляють із IDE. Усі бачать однаковий контент.

Як це працює

        ┌─────────────┐
        │ Web Editor   │
        │ (browser)    │
        └──────┬───────┘
               │ save
               ▼
        ┌─────────────┐          ┌──────────────┐
        │ Content     │  commit  │ Local Git    │  push    ┌──────────────┐
        │ Ledger      │ ───────► │ Repository   │ ───────► │ Remote Repo  │
        │             │          │ (.git)       │          │ (GitHub etc) │
        └─────────────┘          └──────┬───────┘          └──────┬───────┘
               ▲                        │                         │
               │ reconcile              │ pull                    │
               │                 ┌──────▼───────┐                 │
               └──────────────── │ Sync Engine  │ ◄───────────────┘
                                 │ (polling /   │   webhook / poll
                                 │  webhook)    │
                                 └──────────────┘

Веб → Git (вихідна синхронізація)

Ви зберігаєте сторінку у веб-редакторі
Content Ledger записує .md файл на диск
Git рушій автоматично фіксує: docs: update {page-title}
Коміти відправляються у віддалений репозиторій

Git → Веб (вхідна синхронізація)

Хтось відправляє коміт у віддалений репозиторій (з IDE, CI тощо)
Sync Engine виявляє зміну (polling або webhook)
Зміни витягуються в локальний репозиторій
Content Ledger виконує реконсиляцію: файлова система → база даних → пошуковий індекс
WebSocket розсилає оновлення підключеним браузерам

Налаштування

Підключення віддаленого репозиторію

Під час ініціалізації:

docplatform init \
  --workspace-name "Docs" \
  --slug docs \
  --git-url [email protected]:your-org/docs.git \
  --branch main

Після ініціалізації — відредагуйте конфігурацію робочого простору:

# .docplatform/workspaces/{id}/.docplatform/config.yaml
git_remote: [email protected]:your-org/docs.git
git_branch: main
git_auto_commit: true
sync_interval: 300

Перезапустіть сервер або запустіть ручну синхронізацію.

Автентифікація

SSH (рекомендовано)

Згенеруйте deploy key та додайте його до вашого репозиторію:

ssh-keygen -t ed25519 -f ~/.ssh/docplatform_deploy_key -N ""

Встановіть змінну середовища:

export GIT_SSH_KEY_PATH=~/.ssh/docplatform_deploy_key

Додайте публічний ключ (~/.ssh/docplatform_deploy_key.pub) до deploy keys вашого репозиторію. Увімкніть доступ на запис, якщо хочете, щоб DocPlatform відправляв коміти.

HTTPS з токеном

Для HTTPS репозиторіїв вбудуйте токен у URL:

git_remote: https://x-access-token:[email protected]/your-org/docs.git

Або використовуйте Git credential helper, налаштований на хості.

Поведінка синхронізації

Автоматична фіксація

Коли git_auto_commit: true (за замовчуванням), кожне збереження у веб-редакторі створює git коміт. Швидкі редагування в короткому вікні групуються в один коміт.

Формат повідомлення коміту:

docs: update Getting Started

Edited via DocPlatform web editor
Author: [email protected]

Встановіть git_auto_commit: false, щоб вимкнути автоматичну фіксацію. У цьому режимі веб-редактор записує у файлову систему, але не створює git коміти — корисно, якщо ви хочете фіксувати вручну або за розкладом.

Polling

DocPlatform опитує віддалений репозиторій з налаштованим інтервалом (за замовчуванням: 300 секунд / 5 хвилин). Налаштуйте за допомогою:

sync_interval: 60  # check every minute

Менші інтервали означають швидшу синхронізацію, але більше мережевого трафіку.

Webhook

Для миттєвої синхронізації налаштуйте webhook у вашому репозиторії:

GitHub:

Перейдіть до Settings → Webhooks → Add webhook
Payload URL: https://your-domain.com/api/v1/webhooks/github
Content type: application/json
Secret: Встановіть змінну середовища GIT_WEBHOOK_SECRET з відповідним значенням
Events: Оберіть Push events

GitLab:

Перейдіть до Settings → Webhooks
URL: https://your-domain.com/api/v1/webhooks/gitlab
Secret token: Має збігатися з GIT_WEBHOOK_SECRET
Trigger: Push events

Bitbucket:

Перейдіть до Repository settings → Webhooks → Add webhook
URL: https://your-domain.com/api/v1/webhooks/bitbucket
Triggers: Repository push

Ручна синхронізація

Запустіть синхронізацію з веб-інтерфейсу (Settings → Git → Sync Now) або через API:

curl -X POST http://localhost:3000/api/v1/workspaces/{id}/sync \
  -H "Authorization: Bearer {token}"

Вирішення конфліктів

Конфлікти виникають, коли той самий файл змінюється і у веб-редакторі, і через git push між інтервалами синхронізації.

Як виявляються конфлікти

DocPlatform відстежує хеші контенту (SHA-256) для кожної сторінки. При витягуванні віддалених змін порівнюється вхідний хеш із локальним хешем. Якщо обидва відрізняються від спільного предка, оголошується конфлікт.

Що відбувається при конфлікті

Операція збереження або синхронізації повертає HTTP 409 Conflict
Обидві версії (локальна та віддалена) зберігаються
Веб-інтерфейс показує банер конфлікту з варіантами:
- Keep local — відхилити віддалену версію
- Keep remote — відхилити локальну версію
- Download both — завантажити обидва файли для ручного злиття
Створюється гілка конфлікту (conflict/{page-slug}-{timestamp}) з локальною версією

Запобігання конфліктам

Використовуйте webhook замість polling — швидша синхронізація означає менше вікно для конфліктів
Призначте відповідальність за сторінки — один автор на сторінку зменшує ризик колізій
Використовуйте веб-редактор для контенту, IDE для коду — природний розподіл
Короткі інтервали синхронізації — sync_interval: 30 в середовищах із активною співпрацею

Пакетна синхронізація

Коли віддалений push містить більше 20 змінених файлів, DocPlatform переходить у пакетний режим:

Отримує всі змінені файли одним diff
Захоплює м’ютекси для всіх зачеплених шляхів (відсортовані для запобігання deadlock)
Обробляє всі файли в одній транзакції бази даних
Інвалідує кеш прав доступу один раз (а не для кожного файлу)
Надсилає одне WebSocket повідомлення bulk-sync із загальною кількістю змін

Це запобігає шторму сповіщень та надмірному навантаженню на базу даних при відправленні великих змін (наприклад, початковий імпорт репозиторію або масова реструктуризація).

Зберігання конфліктів

Коли виявляється конфлікт, обидві версії зберігаються на диску:

.docplatform/conflicts/
└── {page-id}/
    └── 20250115T103045Z/
        ├── ours.md      # Local version (web editor)
        └── theirs.md    # Remote version (git push)

Конфлікти зберігаються до явного вирішення через веб-інтерфейс або API. Команда docplatform doctor повідомляє про невирішені конфлікти.

Деталі git рушія

DocPlatform використовує гібридний git рушій, який автоматично обирає найкращий бекенд:

Умова	Рушій	Чому
Менше 5 000 файлів	go-git (у процесі)	Швидкий, без зовнішніх залежностей, чистий Go
Більше 5 000 файлів	Нативний git CLI (підпроцес)	Краща обробка великих репозиторіїв, shallow clones
go-git RSS > 512 МБ	Нативний git CLI (резервний)	Безпека пам’яті — запобігає OOM на великих репозиторіях

Пул з 4 паралельних воркерів обробляє git операції для всіх робочих просторів. Кожен робочий простір має власний м’ютекс — операції на різних робочих просторах виконуються паралельно, а операції на одному робочому просторі серіалізуються.

Повідомлення автоматичних комітів мають такий формат:

docs: update {page-title}

Edited via DocPlatform web editor
Author: [email protected]
Committer: DocPlatform <docplatform@local>

Робота з наявними репозиторіями

DocPlatform працює з наявними репозиторіями документації. При підключенні репозиторію:

Репозиторій клонується (або витягується, якщо вже існує локально)
Усі .md файли в директорії docs/ індексуються
Frontmatter аналізується та метадані сторінок зберігаються в SQLite
Пошуковий індекс будується інкрементально

Файли поза docs/ не індексуються та не відображаються в редакторі, але залишаються в git репозиторії недоторканими.

Імпорт з інших платформ

DocPlatform працює з будь-яким Markdown контентом. Ось як мігрувати з поширених платформ:

Джерело	Метод експорту	Примітки
Docusaurus	Пряме копіювання	Вже на основі `.md` — скопіюйте директорію `docs/` як є, додайте frontmatter за потреби
GitBook	JSON експорт → конвертація	Експорт через GitBook API, конвертація в Markdown
Notion	Markdown експорт	Експортуйте робочий простір як Markdown, реструктуруйте в ієрархію `docs/`
Confluence	HTML експорт → конвертація	Експортуйте простори як HTML, конвертуйте в Markdown за допомогою pandoc або аналогів
Wiki.js	Експорт з бази даних	Експортуйте сторінки як Markdown з панелі адміністрування

Загальні кроки міграції:

Експортуйте контент як Markdown файли
Розмістіть їх у git репозиторії в директорії docs/
Додайте YAML frontmatter (як мінімум, title) до кожного файлу
Підключіть репозиторій до DocPlatform
Запустіть docplatform rebuild для примусової повної реконсиляції

Реконсілятор DocPlatform автоматично виявляє всі .md файли, аналізує їх frontmatter, призначає ULID сторінкам без поля id та будує пошуковий індекс.