Rozdział 11: Automatyczna synchronizacja dokumentacji (GitHub Actions)
W Rozdziale 4 kopię dokumentacji projektu odświeżałeś ręcznie, skryptem. W tym rozdziale robimy to automatycznie: gdy wypchniesz zmianę w docs/ repozytorium projektu, GitHub sam zaktualizuje kopię w vaultcie. Mac nie musi być włączony, a kopia nigdy się nie zestarzeje.
Po tym rozdziale każda zmiana dokumentacji na gałęzi
mainprojektu w ciągu minuty trafia do vaulta jako commitsync: docs …, a stamtąd do Obsidiana i do agenta na serwerze.
Wymagania: skrypt synchronizacji z Rozdziału 4, vault na GitHubie (Rozdział 7) i repozytorium projektu na GitHubie.
Jak to działa
push do repo projektu (zmiana w docs/, README, CLAUDE.md…)
│
▼
GitHub Action w repo projektu:
1. pobiera repo projektu i repo vaulta,
2. uruchamia skrypt synchronizacji z vaulta,
3. robi commit "sync: docs moj-projekt (abc1234)" i push do vaulta
│
▼
Obsidian na Macu (wtyczka Git) i agent na serwerze (cron) pobierają zmiany jak zwykle
Kilka zasad, które przyjmujemy:
- akcja uruchamia się tylko wtedy, gdy zmieni się dokumentacja, a nie przy każdej zmianie kodu;
- akcja może pisać wyłącznie w folderze projektu w
01-Projects/(resztę vaulta nawet pomija przy pobieraniu); - dostęp do vaulta daje osobny klucz, który ma dostęp tylko do repozytorium vaulta.
Co zostaje ręczne: akcja kopiuje dokumentację do
01-Projects/. Przetworzenie jej do wiki (ingest) nadal zlecasz agentowi: „przetwórz dokumentację moj-projekt”. To celowe, bo zgodnie ze schematem to Ty decydujesz, co trafia do wiki.
Krok 1 — Skrypt musi działać na Linuksie 💻
GitHub Actions działa na Ubuntu, a nie na macOS. Jedna różnica regularnie psuje skrypty: sed -i (edycja pliku w miejscu).
| Zapis | macOS (BSD sed) | Linux (GNU sed) |
|---|---|---|
sed -i '' 's/a/b/' plik |
✅ | ❌ traktuje '' jako nazwę pliku |
sed -i 's/a/b/' plik |
❌ | ✅ |
sed -i.bak 's/a/b/' plik + rm plik.bak |
✅ | ✅ |
Jeśli Twój skrypt z Rozdziału 4 używa sed -i '', zamień to na wersję z .bak, działającą wszędzie:
sed -i.bak "s#](/images/#](images/#g" "$out"/*.md
rm -f "$out"/*.md.bak
Jak sprawdzić bez czekania na GitHuba: uruchom skrypt na kopii vaulta w kontenerze Linux i porównaj wynik z wersją z Maca. Jeśli
diffnic nie pokaże, skrypt działa tak samo:docker run --rm -v "$PWD/kopia-vaulta:/vault" -v "$HOME/Projekty/moj-projekt:/src:ro" python:3.11-slim bash /vault/_scripts/sync-moj-projekt.sh /src
Zacommituj poprawiony skrypt w vaultcie. Akcja użyje dokładnie tej wersji, która jest na GitHubie.
Krok 2 — Klucz z prawem zapisu do vaulta 💻
Akcja działa w repozytorium projektu, a pisze do repozytorium vaulta. Potrzebuje więc klucza do vaulta. Użyjemy deploy key (dostęp do jednego repozytorium) z prawem zapisu.
Wygeneruj parę kluczy na komputerze, w tymczasowym miejscu:
ssh-keygen -q -t ed25519 -f /tmp/vault_sync_key -N "" -C "moj-projekt-actions-sync"
Klucz publiczny dodaj do repo vaulta z prawem zapisu:
gh repo deploy-key add /tmp/vault_sync_key.pub --repo TWOJ_LOGIN/moja-baza --title "moj-projekt actions sync (write)" --allow-write
Klucz prywatny zapisz jako sekret w repo projektu. Komenda czyta go z pliku i nie wyświetla:
gh secret set OBSIDIAN_VAULT_DEPLOY_KEY --repo TWOJ_LOGIN/moj-projekt < /tmp/vault_sync_key
Usuń lokalne pliki klucza. Nie są już potrzebne, a klucz prywatny nie powinien leżeć na dysku:
rm -f /tmp/vault_sync_key /tmp/vault_sync_key.pub
Sprawdzenie:
gh api repos/TWOJ_LOGIN/moja-baza/keys --jq '.[] | {title, read_only}'
gh secret list --repo TWOJ_LOGIN/moj-projekt
Oczekiwane: klucz moj-projekt actions sync (write) z "read_only": false w vaultcie i sekret OBSIDIAN_VAULT_DEPLOY_KEY w projekcie.
To samo zrobisz w przeglądarce: w repo vaulta Settings → Deploy keys → Add deploy key (zaznacz Allow write access), a w repo projektu Settings → Secrets and variables → Actions → New repository secret.
🔒 Dlaczego deploy key, a nie token osobisty? Token osobisty (PAT) zwykle daje dostęp do wszystkich Twoich repozytoriów. Deploy key działa tylko na jednym repo, a w razie wycieku usuwasz go jednym kliknięciem, bez wpływu na resztę konta.
Krok 3 — Workflow 💻
W repozytorium projektu utwórz plik .github/workflows/sync-obsidian.yml:
name: Sync docs to Obsidian vault
on:
push:
branches: [ main ]
paths:
- 'docs/**'
- 'README.md'
- 'CLAUDE.md'
- '.claude/agents/**'
- 'public/images/**'
workflow_dispatch:
concurrency:
group: sync-obsidian
cancel-in-progress: false
jobs:
sync:
runs-on: ubuntu-latest
steps:
- name: Checkout project
uses: actions/checkout@v4
with:
path: sf
- name: Checkout vault (only the folders the sync touches)
uses: actions/checkout@v4
with:
repository: TWOJ_LOGIN/moja-baza
ssh-key: ${{ secrets.OBSIDIAN_VAULT_DEPLOY_KEY }}
path: vault
sparse-checkout: |
_scripts
01-Projects/moj-projekt
- name: Sync docs into vault
run: bash vault/_scripts/sync-moj-projekt.sh "$GITHUB_WORKSPACE/sf"
- name: Commit and push to vault
working-directory: vault
env:
SHA: ${{ github.sha }}
run: |
git add -A 01-Projects/moj-projekt
if git diff --cached --quiet; then
echo "Brak zmian w dokumentacji — nic do wysłania."
exit 0
fi
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git commit -m "sync: docs moj-projekt (${SHA::7})"
for attempt in 1 2 3; do
git pull --rebase -q && git push && exit 0
sleep 5
done
exit 1
Co tu się dzieje:
| Fragment | Działanie |
|---|---|
paths: |
akcja startuje tylko, gdy zmieni się dokumentacja (dopasuj listę do tego, co kopiuje Twój skrypt) |
workflow_dispatch |
możesz uruchomić akcję ręcznie (przydaje się do testu) |
concurrency |
dwa szybkie pushe nie uruchomią dwóch synchronizacji naraz |
ssh-key: … |
vault jest pobierany i wysyłany kluczem z kroku 2 |
sparse-checkout |
z vaulta pobierane są tylko skrypty i folder projektu; prywatne notatki nawet nie trafiają na maszynę GitHuba |
git add -A 01-Projects/moj-projekt |
do commita trafia wyłącznie folder projektu, nawet gdyby skrypt zrobił coś więcej |
git diff --cached --quiet |
gdy nic się nie zmieniło, akcja kończy się bez pustego commita |
pętla pull --rebase + push |
jeśli w tej samej chwili wtyczka Git z Maca wypchnęła zmiany, akcja je dociąga i ponawia wysyłkę |
Skrypt z vaulta, a nie z projektu. Akcja uruchamia skrypt zapisany w repo vaulta (
vault/_scripts/…). Dzięki temu jest jedna wersja skryptu, a ręczne odświeżenie na Macu i automat dają identyczny wynik.
Krok 4 — Commit i push 💻
git add .github/workflows/sync-obsidian.yml
git commit -m "ci: sync docs to Obsidian vault"
git push
⚠️ Jeśli Twój projekt ma automatyczny deploy przy każdym pushu na
main(jak w tutorialu „CI/CD”), ten push też uruchomi deploy. To nic złego, bo kod się nie zmienił, ale warto o tym wiedzieć.
Krok 5 — Test 💻
Najpierw uruchom akcję ręcznie. Dokumentacja się nie zmieniła, więc akcja powinna zakończyć się bez commita:
gh workflow run sync-obsidian.yml --repo TWOJ_LOGIN/moj-projekt
gh run list --repo TWOJ_LOGIN/moj-projekt --workflow sync-obsidian.yml --limit 1
Gdy status będzie completed success, zrób prawdziwy test: drobną zmianę w dokumentacji (np. literówkę w docs/ albo zdanie w README), commit i push. Po minucie sprawdź vault:
gh api repos/TWOJ_LOGIN/moja-baza/commits --jq '.[0] | "\(.commit.author.name): \(.commit.message)"'
Oczekiwane:
github-actions[bot]: sync: docs moj-projekt (abc1234)
W ciągu kilku minut wtyczka Git pobierze tę zmianę do Obsidiana, a cron na serwerze do agenta.
Weryfikacja rozdziału
- Skrypt synchronizacji działa na Linuksie (
sed -i.bak). - W vaultcie jest deploy key z prawem zapisu, a w projekcie sekret
OBSIDIAN_VAULT_DEPLOY_KEY. - Lokalne pliki klucza są usunięte.
- Ręczne uruchomienie akcji kończy się sukcesem.
- Zmiana w
docs/daje w vaultcie commitsync: docs …odgithub-actions[bot].
Częste problemy
| Objaw | Co zrobić |
|---|---|
| Akcja się nie uruchamia | zmieniony plik nie pasuje do paths:; sprawdź listę albo uruchom ręcznie (gh workflow run) |
Permission denied (publickey) przy pobieraniu vaulta |
brak sekretu albo zła nazwa; sprawdź gh secret list |
ERROR: The key you are authenticating with has been marked as read only |
deploy key dodany bez Allow write access; usuń go i dodaj ponownie z --allow-write |
Błąd w kroku „Sync docs”: sed: can't read … |
skrypt ma jeszcze sed -i '' (wersja tylko na macOS); popraw jak w kroku 1 |
| Push odrzucony po 3 próbach | trwał konflikt z równoczesną zmianą; uruchom akcję ponownie (gh run rerun) |
| Kopia zmieniła się, ale wiki nie | to normalne: poproś agenta „przetwórz dokumentację moj-projekt” |
Bezpieczeństwo
- Klucz ma dostęp tylko do repozytorium vaulta. Gdyby wyciekł, usuwasz go w Settings → Deploy keys i generujesz nowy.
- Akcja pobiera tylko skrypty i folder projektu, a commituje tylko folder projektu.
- Każdy commit akcji ma autora
github-actions[bot]i skrót commita z projektu, więc w historii vaulta zawsze widać, skąd przyszła zmiana. - Akcja nie ma dostępu do
03-Private, bo nie pobiera tego folderu.
Podsumowanie
- ✅ Skrypt synchronizacji działa tak samo na macOS i na Linuksie.
- ✅ Repo projektu ma ograniczony dostęp do zapisu w vaultcie (deploy key + sekret).
- ✅ Każda zmiana dokumentacji na
mainsama trafia do vaulta jako commitsync: docs …. - ✅ Wiesz, co zostaje ręczne: przetworzenie nowej dokumentacji do wiki.
To koniec przewodnika. Przeszedłeś całą drogę: od pierwszego uruchomienia Obsidiana, przez strukturę i schemat LLM Wiki, pierwszy ingest z agentem AI, prywatne repozytorium i automatyczną synchronizację, agenta na serwerze, który czyta Twoją bazę 24/7, aż po dokumentację projektów, która sama trafia do vaulta. Teraz to Twój „drugi mózg”: im więcej dobrych źródeł mu dasz, tym bardziej będzie przydatny. 🎉