Podepnij repozytorium GitHub, a każdy git push do brancha produkcyjnego uruchomi automatyczny build i deploy. Bez klikania w panel.
Jedno repozytorium = jedna aplikacja. Plik
saplo.yaml musi leżeć w katalogu głównym repo. Monorepo z osobnym frontendem i backendem podziel na dwa repozytoria - inaczej Git Push wykryje tylko jeden saplo.yaml. Drugą aplikację możesz w międzyczasie wdrażać przez CLI.
Jak to działa
Ty: git push origin main
|
v
GitHub App "Saplo Deploy"
wykrywa push i wysyła webhook
|
v
POST https://panel.saplo.pl/api/v1/webhooks/github/
- Saplo weryfikuje podpis HMAC (SHA-256)
- sprawdza, czy pushed branch == branch produkcyjny
|
v
Saplo pobiera saplo.yaml z repo @ konkretny commit SHA
- odczytuje konfigurację buildu
- jeśli brak saplo.yaml: używa konfiguracji z ostatniego deployu
|
v
Deployment trafia do kolejki (source="git", status="queued")
|
v
Worker Celery:
- klonuje repo do LXC kontenera (git clone --depth 1 @ commit SHA)
- uruchamia builder (npm install + build, pip install, itp.)
- wdraża, restartuje serwis, healthcheck
|
v
Status raportowany w commicie na GitHubie
zielona kropka = sukces
czerwony krzyzyk = błąd
Cały cykl od git push do działającej nowej wersji zajmuje zwykle 1-3 minuty.
Wymagania wstępne
Zanim połączysz repo, upewnij się, że:
- Aplikacja istnieje w panelu Saplo. Łączenie repo odbywa się z poziomu konkretnej aplikacji - jeśli jej nie ma, najpierw utwórz ją zgodnie z instrukcją deployu z panelu.
- W katalogu głównym repo masz plik
saplo.yaml. Możesz go wygenerować poleceniem:
$ saplo init
albo napisać ręcznie (patrz referencja saplo.yaml).
Plik musi być zacommitowany i wypchnięty do repo:
$ git add saplo.yaml
$ git commit -m "add saplo.yaml"
$ git push origin main
Jeśli Saplo nie znajdzie
saplo.yaml w repo przy danym commicie, użyje konfiguracji z poprzedniego udanego deployu. Przy pierwszym deployu bez tego pliku - deploy nie powiedzie się z błędem.
Krok 1: Połącz repozytorium GitHub
Sekcja "Git / CI-CD" w panelu pokazuje listę połączeń - ale samo łączenie odbywa się ze szczegółów konkretnej aplikacji, nie z widoku listy.
- Zaloguj się do panelu Saplo na
panel.saplo.pl. - Wejdź do sekcji Aplikacje i kliknij nazwę aplikacji, którą chcesz połączyć z repo.
- Na stronie szczegółów aplikacji znajdź sekcję Git / CI-CD lub przycisk "Połącz repo".
- Kliknij "Połącz GitHub" - zostaniesz przekierowany do GitHuba.
- Na GitHubie pojawi się ekran instalacji GitHub App "Saplo Deploy". Wybierz Only select repositories i wskaż konkretne repo (zalecane), lub "All repositories".
- Kliknij "Install & Authorize" - GitHub przekieruje Cię z powrotem do panelu.
Po powrocie do panelu, na stronie Git / CI-CD zobaczysz aplikację z etykietą "Połączone".
Krok 2: Sprawdź konfigurację brancha
Domyślna gałąź produkcyjna to main. Jeśli chcesz zmienić (np. na production lub master), ustaw to w saplo.yaml:
branches:
production: main
Tylko pushe do tego brancha uruchomią deploy. Pushe do innych gałęzi są ignorowane - możesz pushować swobodnie bez obawy o przypadkowy deploy.
Krok 3: Pierwszy push
$ git add .
$ git commit -m "first deploy via Saplo"
$ git push origin main
W ciągu kilku sekund:
- GitHub wykrywa push i wysyła webhook do Saplo
- W panelu Saplo, w sekcji Deploymenty, pojawi się nowy wpis z statusem "W kolejce", a potem "W trakcie"
- Po zakończeniu status zmieni się na "Sukces" lub "Błąd"
- Przy commicie na GitHubie pojawi się status check (zielona lub czerwona kropka)
Śledzenie postępu deployu
W panelu Saplo:
- Wejdź w Aplikacje, wybierz aplikację, zakładka Deploymenty
- Widać listę wszystkich deployów z datą, statusem, SHA commita i wiadomością commita
- Kliknij w deployment, żeby zobaczyć szczegółowe logi buildu
Na GitHubie:
- Przy commicie pojawia się check "Saplo Deploy / nazwa-aplikacji"
- Zielona kropka = deploy zakończony sukcesem
- Czerwony krzyżyk = coś poszło nie tak, kliknij "Details" dla logów
Przez CLI:
$ saplo logs --follow
Co się dzieje gdy deploy się nie uda
Saplo nie wycofa działającej wersji przy błędzie. Jeśli build lub healthcheck zakończy się błędem:
- Nowy deployment dostaje status
failed - Poprzednia wersja aplikacji nadal działa
- Przy commicie na GitHubie pojawia się czerwony krzyżyk
- Logi błędu są dostępne w panelu (szczegóły deploymentu)
Żeby naprawić: popraw kod, zacommituj i pushuj ponownie.
Najczęstsze pytania
Mam prywatne repo - czy zadziała?
Tak. GitHub App "Saplo Deploy" instalujesz na swoim koncie/organizacji i wybierasz, do których repo dać dostęp. Prywatne repo działa identycznie jak publiczne. Saplo pobiera kod przez instalację App, nie przez klucze SSH.
Push poszedł, ale deploy się nie uruchomił.
Sprawdź kilka rzeczy:
- Czy zmiany trafiły do właściwego brancha? Deploy odpala się tylko z brancha produkcyjnego (domyślnie
main). - Czy GitHub App jest nadal zainstalowana? GitHub: Settings - Applications - Installed GitHub Apps.
- Czy auto-deploy jest włączony? W panelu Saplo, w szczegółach połączenia, sprawdź pole "Auto-deploy".
Jak zmienić branch produkcyjny?
Edytuj saplo.yaml, zmień pole branches.production, zacommituj i wypchnij:
branches:
production: release # zamiast main
Czy mogę połączyć kilka aplikacji z różnymi repo?
Tak. Każda aplikacja Saplo łączy się z dokładnie jednym repo (relacja 1:1). Możesz mieć wiele aplikacji, każda z własnym repo i własnym branchem produkcyjnym.
Jak odłączyć repo?
W panelu Saplo: szczegóły aplikacji - sekcja Git - przycisk "Rozłącz repo". Po odłączeniu pushe przestają triggerować deploymenty. Możesz nadal wdrażać ręcznie przez
saplo deploy lub przez panel.Metoda alternatywna: Deploy Key (GitLab, Bitbucket, inne)
Jeśli używasz GitLab, Bitbucket lub innego hostingu Git, możesz połączyć repo przez Deploy Key i ręcznie skonfigurowany webhook.
Krok 1: Wygeneruj klucz w panelu
- Wejdź w szczegóły aplikacji - sekcja Git
- Kliknij "Połącz repo ręcznie"
- Saplo generuje parę kluczy SSH (RSA 4096) i wyświetla klucz publiczny oraz unikalny webhook URL
Krok 2: Dodaj klucz do repo
- GitHub: Settings - Deploy keys - Add deploy key - wklej klucz publiczny, zaznacz "Allow read access"
- GitLab: Settings - Repository - Deploy keys - wklej klucz publiczny
- Bitbucket: Repository settings - Access keys - wklej klucz publiczny
Krok 3: Skonfiguruj webhook
W ustawieniach repo dodaj webhook:
- URL:
https://panel.saplo.pl/api/v1/webhooks/git/?token=TWOJ_TOKEN(skopiuj pełny URL z panelu) - Content type:
application/json - Trigger: Push events (tylko push)
- Secret: zostaw puste (token jest w URL)
Krok 4: Push
$ git push origin main
Saplo odbierze webhook, sklonuje repo przez klucz SSH i uruchomi deploy.
