Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

GitHub Actions: automatyczne wdrażanie aplikacji na VPS po pushu

Paczka przechodzi przez przemysłową bramkę kontrolną.

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.

Taśma prowadzi paczkę przez kontrolę do miejsca odbioru.
Wdrożenie powinno nastąpić dopiero po przejściu testów.

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
Klucz i karta odcisku palca leżą przy zamku urządzenia.
Klucz klienta i zweryfikowana tożsamość serwera pełnią różne role.

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.

Mechaniczny przełącznik wybiera jedno z dwóch oznaczonych wydań.
Zachowanie poprzedniego wydania pozwala szybko przełączyć pliki z powrotem.

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

Data publikacji: 11.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *