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 = blad
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 sam 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 pushowałeś 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.