Automatyczne wdrożenie nie powinno oznaczać, że każdy push nadpisuje pliki działającej strony bez kontroli. Potrzebujesz sprawdzonej paczki, ograniczonego dostępu do serwera i sposobu ustalenia, która wersja rzeczywiście odpowiada przez HTTP. Dopiero taki proces warto uruchamiać z GitHub Actions.
Poniższy przykład wdraża statyczną aplikację WWW z katalogu public/ na VPS z Nginx. To kompletna podstawa procesu, ale nie uniwersalny skrypt dla backendu z bazą. Dla Node.js, PHP czy kontenerów trzeba dodatkowo zaprojektować restart procesu, migracje i zgodność danych.
Jak będzie działać wdrożenie?
Push do main uruchomi workflow. Runner pobierze repozytorium, sprawdzi podstawowe warunki paczki, zapisze identyfikator wydania i prześle archiwum przez SSH. Na VPS-ie pliki trafią do nowego katalogu. Dopiero potem dowiązanie current zostanie przełączone na to wydanie.

Na końcu runner pobierze version.txt spod publicznego adresu i porówna wynik z oczekiwanym identyfikatorem. Zielony status transferu SSH sam w sobie nie potwierdza, że użytkownik widzi nową stronę.
Do przygotowania VPS-a potrzebujesz konta administracyjnego, Nginx oraz działającej domeny z HTTPS. Sam workflow będzie korzystał z osobnego konta deploy. Podstawy logowania kluczem znajdziesz w poradniku SSH bez hasła z użyciem kluczy.
Przygotuj ograniczone konto na serwerze
Poniższe jednorazowe polecenia dotyczą serwera Ubuntu lub Debian. Wykonuje je administrator. Jeśli konto deploy już istnieje, najpierw sprawdź jego rolę zamiast tworzyć lub przerabiać je w ciemno.
sudo adduser --disabled-password --gecos '' deploy
sudo install -d -o deploy -g deploy -m 755 /var/www/demo
sudo install -d -o deploy -g deploy -m 755 /var/www/demo/releases
sudo install -d -o deploy -g deploy -m 700 /home/deploy/.ssh
sudo install -d -o deploy -g deploy -m 700 /home/deploy/incoming
Dodaj publiczną część dedykowanego klucza wdrożeniowego do /home/deploy/.ssh/authorized_keys, ustaw właściciela deploy:deploy i tryb 600. Nie używaj prywatnego klucza swojego codziennego konta. Konto wdrożeniowe nie potrzebuje sudo ani przynależności do grupy docker w tym scenariuszu.
Jako prefiks wpisu klucza możesz zastosować restrict, aby ograniczyć przekazywanie portów i przydzielanie terminala. Nie jest to ograniczenie wszystkich poleceń powłoki. Ten przykład nadal pozwala wykonać polecenia z prawami użytkownika deploy, dlatego klucz i repozytorium muszą pozostać zaufane. W bardziej restrykcyjnym wariancie stosuje się osobny, sprawdzony program odbierający wdrożenia.
Nginx musi mieć prawo przejścia przez /var/www/demo i odczytu plików, ale nie potrzebuje prawa zapisu. Nie udostępniaj przez serwer WWW katalogu incoming, kluczy ani całego repozytorium.
Skieruj Nginx na aktywne wydanie
W istniejącym bloku HTTPS dla domeny aplikacji ustaw:
root /var/www/demo/current;
index index.html;
location / {
try_files $uri $uri/ =404;
}
location = /version.txt {
add_header Cache-Control "no-store";
}
To fragment konfiguracji, nie pełny zamiennik ustawień TLS. Zachowaj swoją domenę, certyfikaty i potrzebne nagłówki. Przed przeładowaniem uruchom sudo nginx -t. Pierwsze wdrożenie utworzy current; do tego czasu domena może odpowiadać błędem braku plików.
Nie włączaj cache dla version.txt, również na CDN, jeśli stoi przed serwerem. W przeciwnym razie test może sprawdzać poprzednią odpowiedź z pamięci podręcznej. W aplikacji SPA dostosuj regułę try_files do routingu, zamiast bezrefleksyjnie kopiować wariant statyczny.
Sekrety GitHub i weryfikacja hosta
W ustawieniach repozytorium, w sekretach Actions, zapisz:
| Nazwa | Zawartość |
|---|---|
| DEPLOY_HOST | Nazwa DNS albo adres VPS-a, bez prefiksu ssh:// |
| DEPLOY_KEY | Prywatny klucz dedykowany kontu deploy |
| DEPLOY_KNOWN_HOSTS | Zweryfikowany wpis known_hosts serwera |
| SITE_URL | Publiczny adres HTTPS aplikacji, np. https://app.example.com |

DEPLOY_KEY potwierdza tożsamość klienta wobec serwera. DEPLOY_KNOWN_HOSTS pozwala klientowi sprawdzić serwer. To dwa różne elementy. Nie zastępuj drugiego opcją StrictHostKeyChecking=no.
Klucz hosta odczytaj przez zaufaną konsolę dostawcy lub wcześniej zweryfikowane połączenie. Porównaj odcisk z ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub. Wpis known_hosts musi zawierać nazwę używaną w DEPLOY_HOST, typ klucza i jego publiczną wartość. Samo wykonanie ssh-keyscan w workflow pobiera klucz, ale nie potwierdza jego autentyczności.
Przykład zakłada port SSH 22. Dla innego portu trzeba zmienić opcje SSH/SCP i format nazwy w known_hosts. Firewall musi pozwalać runnerowi na połączenie z SSH. Nie otwieraj niepotrzebnie wszystkich usług serwera.
Skrypt aktywacji wydania
W repozytorium utwórz scripts/activate-release.sh i zapisz go z zakończeniami linii LF:
#!/usr/bin/env bash
set -euo pipefail
umask 022
release=${1:?Podaj identyfikator wydania}
[[ "$release" =~ ^[0-9a-f]{40}-[0-9]+-[0-9]+$ ]] || exit 2
base=/var/www/demo
archive="$HOME/incoming/$release.tgz"
target="$base/releases/$release"
exec 9>"$base/deploy.lock"
flock -n 9 || { echo 'Inne wdrozenie trwa'; exit 1; }
test -s "$archive"
mkdir "$target"
tar --no-same-owner --no-same-permissions -xzf "$archive" -C "$target"
test -s "$target/index.html"
test -s "$target/version.txt"
previous=$(readlink "$base/current" || true)
printf 'Poprzednie wydanie: %s\n' "$previous"
ln -s "releases/$release" "$base/.next-$release"
mv -Tf "$base/.next-$release" "$base/current"
rm -- "$archive"
Skrypt pracuje tylko w katalogu przeznaczonym dla tej aplikacji. Walidacja identyfikatora ogranicza możliwość podstawienia innej ścieżki. Blokada flock chroni przełączenie również przed drugą sesją uruchomioną poza GitHub Actions. Paczka musi pochodzić z zaufanego procesu budowania; to nie jest serwis przyjmujący dowolne archiwa od użytkowników.
Nowy katalog powstaje przed zmianą dowiązania. Jeżeli rozpakowanie lub kontrola plików zawiedzie, current nadal wskazuje poprzednią wersję. Zmiana dowiązania przez mv na tym samym systemie plików daje pojedyncze przełączenie ścieżki. Nie gwarantuje jednak, że wielożądaniowa sesja przeglądarki pobierze wszystkie zasoby z jednej wersji. Dla większych aplikacji stosuj wersjonowane nazwy assetów i przemyślaną retencję starych plików.
Workflow uruchamiany po pushu
Repozytorium powinno zawierać przynajmniej public/index.html oraz skrypt aktywacji. W .github/workflows/deploy.yml zapisz:
name: Deploy static site
on:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: production-static-site
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: Check and package
shell: bash
run: |
set -euo pipefail
bash -n scripts/activate-release.sh
test -s public/index.html
test -z "$(find public -type l -print -quit)"
release="$GITHUB_SHA-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
printf '%s\n' "$release" > public/version.txt
tar -czf site.tgz -C public .
echo "RELEASE=$release" >> "$GITHUB_ENV"
- name: Upload and activate
shell: bash
env:
DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
DEPLOY_KNOWN_HOSTS: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
SITE_URL: ${{ secrets.SITE_URL }}
run: |
set -euo pipefail
umask 077
key="$RUNNER_TEMP/deploy-key"
known="$RUNNER_TEMP/deploy-known-hosts"
trap 'rm -f -- "$key" "$known"' EXIT
printf '%s\n' "$DEPLOY_KEY" > "$key"
printf '%s\n' "$DEPLOY_KNOWN_HOSTS" > "$known"
opts=(-i "$key" -o BatchMode=yes -o IdentitiesOnly=yes
-o StrictHostKeyChecking=yes -o "UserKnownHostsFile=$known")
scp "${opts[@]}" site.tgz "deploy@$DEPLOY_HOST:incoming/$RELEASE.tgz"
ssh "${opts[@]}" "deploy@$DEPLOY_HOST" \
"bash -s -- '$RELEASE'" < scripts/activate-release.sh
actual=$(curl --fail --silent --show-error --retry 3 \
--max-time 15 "${SITE_URL%/}/version.txt?release=$RELEASE")
test "$actual" = "$RELEASE"
Pełny SHA akcji checkout wskazuje konkretną rewizję. Aktualizuj go świadomie po sprawdzeniu zmian. persist-credentials: false zapobiega pozostawieniu danych uwierzytelniających checkout w konfiguracji Git po tym kroku. Uprawnienia tokenu workflow ograniczamy do odczytu zawartości.
Sekrety przekazujemy jako zmienne środowiskowe, a następnie cytujemy w Bash. Nie buduj poleceń przez bezpośrednie wklejanie do skryptu tytułów pull requestów lub innych tekstów kontrolowanych przez zewnętrznych użytkowników.
Kontrola index.html to tylko test dymny demonstracji. Dla prawdziwego projektu dodaj testy jednostkowe, budowę, analizę zależności i sprawdzenie wyniku przed pakowaniem. Katalog public/ powinien zawierać wyłącznie materiały przeznaczone do publicznego udostępnienia, bez .env, backupów i kluczy.
Kolejność, błędy i wycofanie zmiany
Grupa concurrency zapobiega równoległemu wykonywaniu workflow z tą samą grupą. cancel-in-progress: false nie przerywa aktywnego wdrożenia. Nie traktuj tego jednak jako gwarantowanej kolejki każdego commitu w kolejności pushów. GitHub może zastąpić oczekujące uruchomienie nowszym; strategię wdrożeń dobierz do tego zachowania.

Jeżeli test publicznego adresu zawiedzie po przełączeniu, workflow będzie czerwony, ale nowa wersja pozostanie aktywna. Ten przykład nie wykonuje automatycznego rollbacku. Sprawdź logi i poprzednią ścieżkę wydrukowaną przez skrypt. Ręczny powrót jako deploy może wyglądać tak:
cd /var/www/demo
exec 9>deploy.lock
flock -n 9 || exit 1
test -s releases/POPRZEDNI_IDENTYFIKATOR/index.html
ln -s releases/POPRZEDNI_IDENTYFIKATOR .rollback
mv -Tf .rollback current
Zastąp identyfikator konkretną zachowaną wersją i upewnij się, że .rollback nie pozostało po wcześniejszej próbie. Potem ponownie sprawdź odpowiedź HTTP. Nie uruchamiaj rollbacku równolegle z innym wdrożeniem.
Dla aplikacji z bazą cofnięcie plików nie cofa migracji. Potrzebne są kompatybilne zmiany schematu i osobna procedura odzyskania danych. Jeśli budujesz aplikację kontenerową, najpierw przygotuj przewidywalny artefakt zgodnie z poradnikiem budowania własnego obrazu Docker, a następnie zaprojektuj jego uruchomienie na serwerze.
FAQ
Czy workflow musi logować się jako root?
Nie. Dla statycznej aplikacji wystarczy konto zapisujące pliki w jednym katalogu. Unikaj udzielania sudo tylko po to, żeby ominąć źle ustawione prawa.
Jak rozpoznać, że wdrożono właściwy commit?
Zapisz identyfikator wydania w artefakcie i porównaj go z odpowiedzią działającej strony. Sam numer przebiegu w interfejsie GitHub nie potwierdza stanu aplikacji.
Dlaczego SSH odrzuca klucz hosta?
Może zmieniła się maszyna, nazwa, port lub klucz serwera. Zweryfikuj to przez zaufany kanał. Nie wyłączaj sprawdzania tożsamości, żeby wymusić zielony wynik.
Czy wdrażać kod z każdego pull requestu?
Nie do produkcji z dostępem do sekretów. Dla propozycji zmian uruchamiaj testy bez klucza produkcyjnego. Chroniona gałąź i przegląd zmian workflow pomagają kontrolować, kto może uruchomić wdrożenie.
Jak dodać ręczne zatwierdzanie?
Użyj środowiska GitHub Environment z regułami ochrony i przypisz je do zadania. Dostępność funkcji zależy od planu oraz widoczności repozytorium. W pokazanym wariancie nie ma ręcznego zatwierdzenia: push do main uruchamia wdrożenie.
Źródła
- Workflow syntax, GitHub Docs - struktura workflow i uprawnienia.
- Control concurrency, GitHub Docs - równoległość i oczekujące przebiegi.
- Secure use reference, GitHub Docs - akcje, sekrety i niezaufane dane.
- Using secrets, GitHub Docs - przekazywanie sekretów.
- actions/checkout, GitHub - konfiguracja pobierania repozytorium.
- Deployments and environments, GitHub Docs - środowiska i reguły ochrony.
- ssh_config, OpenBSD/OpenSSH - weryfikacja hosta i opcje klienta.
- sshd, OpenBSD/OpenSSH - ograniczenia authorized_keys.
- HTTP core module, Nginx - root i obsługa plików.
Data publikacji: 11.10.2026.

Dyskusja