CI/CD dla strony statycznej – GitHub Actions w praktyce

CI/CD (Continuous Integration / Continuous Deployment) to automatyzacja drogi kodu od commit do publikacji. Dla strony statycznej – Astro, Next.js w trybie export, Hugo, Eleventy – oznacza to prosty, przewidywalny pipeline: każda zmiana jest budowana, testowana i wdrażana bez ręcznych kroków. W tym artykule pokazuję kompletny workflow GitHub Actions: od lintu i testów, przez build, po deployment z preview na Vercel.

Dlaczego strona statyczna potrzebuje CI/CD

Nawet prosta strona zyskuje na automatyzacji:

• Powtarzalność – build zawsze w tym samym środowisku; „u mnie działa“ znika z języka zespołu.
• Wykrywanie błędów wcześnie – lint, testy i build lecą na każdej zmianie, zanim trafi na produkcję.
• Preview dla każdego PR – recenzent widzi działającą stronę, nie tylko diff.
• Szybsze wdrożenia – deploy to efekt uboczny merge’a, a nie wieczorne ręczne sesje.
• Audyt – w historii workflow widać, co i kiedy zostało zbudowane i wdrożone.

Struktura workflow GitHub Actions

Workflow to plik YAML w .github/workflows/, który definiuje zdarzenia wyzwalające (triggers), zadania (jobs) i kroki (steps). Dla strony statycznej wystarczy jeden plik ci.yml:

name: CI/CD

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint-and-test:
    name: Lint i testy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run test

  build:
    name: Build statyczny
    needs: lint-and-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: site
          path: dist/

  deploy:
    name: Deploy na produkcję
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
        env:
          PUBLIC_SITE_URL: ${{ secrets.PUBLIC_SITE_URL }}
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

Warto zwrócić uwagę na kluczowe elementy:

• Triggers – workflow działa na push do main i na każdym pull requestcie. Oddzielnie można wywoływać go ręcznie przez workflow_dispatch.
• Kolejność zadań – needs wymusza: testy → build → deploy. Build nie ruszy, dopóki testy nie przejdą.
• Cache zależności – cache: npm skraca czas wykonania z kilku minut do kilkudziesięciu sekund.

Testy i lint w pipeline

Nie przepuszczaj zmian bez weryfikacji. Dla strony statycznej standardowy zestaw to:

• Lint (eslint, astro check, tsc --noEmit) – błędy składni i typów odpadają na starcie.
• Testy jednostkowe – logika aplikacji (walidatory formularzy, stan, przeliczanie wartości) testowana w izolacji.
• Testy e2e – Playwright lub Cypress przechodzi przez kluczowe ścieżki użytkownika: nawigację, formularz kontaktowy, koszyk.
• Sprawdzenie linków – narzędzie typu lychee waliduje, że żadna podstrona nie ma martwego odnośnika.

Preview deployments

Preview to środowisko, które powstaje dla każdego pull requesta. Na Vercel wystarczy podpiąć repozytorium – platforma sama tworzy preview dla każdej gałęzi i komentuje link w PR. W pipeline z powyższego przykładu można je uzyskać bez osobnego joba, uruchamiając vercel-action bez flagi --prod na zdarzeniu pull_request.

Preview przydaje się do:

• przeglądu wizualnego zmian przez projektanta,
• testów akceptacyjnych klienta przed mergem,
• weryfikacji SEO (metadane, canonical, sitemap) na prawdziwym URL.

Zmienne środowiskowe i sekrety

Nigdy nie trzymaj kluczy w repozytorium. Sekrety konfigurujesz w Settings → Secrets and variables → Actions:

• VERCEL_TOKEN – token dostępowy konta Vercel,
• VERCEL_ORG_ID i VERCEL_PROJECT_ID – identyfikatory projektu,
• PUBLIC_SITE_URL – publiczny adres strony, potrzebny do poprawnych canonical i sitemap.

Sekrety w workflow odwołujesz przez ${{ secrets.NAZWA }}, a zmienne publiczne przez ${{ vars.NAZWA }} lub env. Pamiętaj: nazwy zaczynające się od PUBLIC_ trafiają do JavaScriptu po stronie klienta, więc nigdy nie wkładaj tam niczego poufnego.

Ochrona gałęzi i jakość zmian

Sam pipeline nie wystarczy – zabezpiecz gałąź main:

• wymagaj przejścia wszystkich checków przed mergem (branch protection rules),
• wymagaj co najmniej jednej recenzji,
• używaj merge queue przy dużym zespole, aby nie kolidowały ze sobą równoległe zmiany.

Debugowanie pipeline’u

Gdy workflow padnie, diagnoza zaczyna się w zakładce Actions: klikasz czerwony job i przeglądasz logi konkretnego kroku. Najczęstsze przyczyny awarii i szybkie rozwiązania:

• npm ci nie może znaleźć package-lock.json – zależności były instalowane innym menedżerem (bun, pnpm); użyj odpowiedniego polecenia (bun install --frozen-lockfile, pnpm install --frozen-lockfile) lub wygeneruj lockfile i wgraj go do repo.
• Build działa lokalnie, pada w CI – zwykle różnica w wersji Node lub zmiennych środowiskowych; ustaw node-version jawnie i zdefiniuj wymagane zmienne w env kroku.
• Cache zepsuty – usunięcie cache: npm na jeden przebieg albo ręczne wyczyszczenie cache w ustawieniach Actions rozwiąże problem z nieaktualnymi zależnościami.
• Timeout – domyślnie każdy krok ma 6 godzin, ale joby całego workflow bywają ograniczane; podziel długie zadania na mniejsze joby równoległe.

Warto też dodać krok publikujący artefakt builda (jak w przykładzie wyżej), żeby logi i wynik budowy dało się pobrać z poziomu GitHub – przyspiesza to pracę, gdy błąd pojawia się dopiero w wygenerowanym kodzie.

Podsumowanie

CI/CD dla strony statycznej to kilkadziesiąt linii YAML, które zamieniają deploy w codzienną, bezpieczną rutynę: lint i testy na każdej zmianie, preview na każdym pull requescie, produkcja aktualizowana tylko z main i tylko po zielonych checkach. Zacznij od prostego workflow z powyższego przykładu, a potem dodawaj kolejne warstwy – testy e2e, sprawdzanie linków, monitoring wydajności. Jeśli chcesz wiedzieć, co dzieje się po stronie platformy – zobacz, jak skonfigurować deployment na Vercel.