11

Rozdział 11 z 11

Automatyczna synchronizacja dokumentacji (GitHub Actions)

Opublikowany

Ostatni ręczny krok znika: gdy wypchniesz zmianę dokumentacji projektu, GitHub Action uruchamia skrypt synchronizacji i robi commit do vaulta. Pokazujemy przenośny skrypt, klucz z ograniczonym dostępem i test.

Czego się nauczysz

  • Skrypt działający na Linuksie (sed -i.bak)
  • Deploy key z prawem zapisu i sekret repozytorium
  • Workflow uruchamiany tylko przy zmianie dokumentacji
  • Sparse checkout i commit tylko folderu projektu
  • Test ręczny i prawdziwy

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 main projektu w ciągu minuty trafia do vaulta jako commit sync: 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 diff nic 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 commit sync: docs … od github-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 main sama trafia do vaulta jako commit sync: 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. 🎉

Narzędzia / paczki

GitHub Actions actions/checkout SSH deploy key gh secret

Spis treści