Preview Deployments i środowiska staging

W Metropolii Quantum 2150 żaden system nie trafia bezpośrednio na serwery produkcyjne. Każda zmiana przechodzi przez rygorystyczny proces weryfikacji — od preview deployments dla poszczególnych Pull Requestów, przez środowisko staging, aż po kontrolowaną promocję na produkcję. Taki pipeline zapewnia, że mieszkańcy Quantum City nigdy nie doświadczą wadliwego kodu.

Czym są Preview Deployments?

Preview Deployments to automatyczne wdrożenia aplikacji generowane dla każdego Pull Requesta. Każdy PR otrzymuje własny, unikalny URL, pod którym można przetestować zmiany przed ich zmergowaniem do głównej gałęzi.

Vercel — platforma stworzona przez twórców Next.js — oferuje najlepsze wsparcie dla Preview Deployments. Ale inne platformy, jak Netlify czy AWS Amplify, również wspierają ten koncept.

Jak działają Preview Deployments na Vercel?

1. Tworzysz Pull Request na GitHubie
2. Vercel automatycznie wykrywa nowy PR
3. Buduje aplikację z kodem z tego PR
4. Generuje unikalny URL (np.

   project-git-feature-xyz-team.vercel.app

   )
5. Dodaje komentarz do PR z linkiem do preview

1# Przykładowe URL-e Preview Deployments:
2# PR #42: my-app-git-feature-login-myteam.vercel.app
3# PR #43: my-app-git-fix-header-myteam.vercel.app
4# PR #44: my-app-git-update-api-myteam.vercel.app
5
6# Każdy URL jest unikalny i działa dopóki PR istnieje

Konfiguracja Vercel dla Preview Deployments

1// vercel.json
2{
3  "git": {
4    "deploymentEnabled": {
5      "main": true,
6      "staging": true
7    }
8  },
9  "github": {
10    "autoAlias": true,
11    "autoJobCancelation": true,
12    "silent": false
13  },
14  "headers": [
15    {
16      "source": "/(.*)",
17      "headers": [
18        {
19          "key": "X-Robots-Tag",
20          "value": "noindex"
21        }
22      ]
23    }
24  ]
25}

Ważna uwaga: Preview Deployments powinny mieć nagłówek

X-Robots-Tag: noindex

Środowiska deployment (dev → staging → prod)

W profesjonalnych projektach stosuje się wielopoziomowy pipeline wdrożeń:

Hierarchia środowisk

1Development (dev)     → Lokalna maszyna developera
2    ↓
3Preview               → Automatyczne per-PR (Vercel Preview)
4    ↓
5Staging               → Odwzorowanie produkcji (testy końcowe)
6    ↓
7Production (prod)     → Serwery produkcyjne (użytkownicy końcowi)

Branch-based deployments

Każda gałąź Gita może być mapowana na inne środowisko:

1# Konfiguracja branch → environment w Vercel:
2# main        → Production  (app.quantum-city.com)
3# staging     → Staging     (staging.quantum-city.com)
4# develop     → Development (dev.quantum-city.com)
5# feature/*   → Preview     (auto-generated URL)
6
7# Workflow developera:
8git checkout -b feature/new-dashboard
9# ... kodowanie ...
10git push origin feature/new-dashboard
11# → Automatycznie: Preview Deployment!
12
13# Po review i merge do staging:
14git checkout staging
15git merge feature/new-dashboard
16git push origin staging
17# → Automatycznie: Staging Deployment!
18
19# Po testach na staging, merge do main:
20git checkout main
21git merge staging
22git push origin main
23# → Automatycznie: Production Deployment!

Zmienne środowiskowe per environment

Każde środowisko ma własne zmienne:

1// Vercel CLI - dodawanie zmiennych per środowisko
2// vercel env add DATABASE_URL development
3// vercel env add DATABASE_URL preview
4// vercel env add DATABASE_URL production
5
6// W kodzie sprawdzamy środowisko:
7// app/api/config/route.ts
8import { NextResponse } from 'next/server';
9
10export async function GET() {
11  const environment = process.env.VERCEL_ENV; // 'production' | 'preview' | 'development'
12  const gitBranch = process.env.VERCEL_GIT_COMMIT_REF; // np. 'feature/login'
13  const commitSha = process.env.VERCEL_GIT_COMMIT_SHA; // hash commitu
14
15  return NextResponse.json({
16    environment,
17    branch: gitBranch,
18    commit: commitSha?.slice(0, 7),
19    // Różne bazy danych per środowisko
20    database: environment === 'production'
21      ? 'prod-cluster'
22      : environment === 'preview'
23        ? 'preview-cluster'
24        : 'dev-cluster',
25  });
26}

Protected Deployments

W środowisku staging i preview warto chronić dostęp, aby niepowołane osoby nie widziały nieopublikowanych zmian:

1// middleware.ts - ochrona preview i staging
2import { NextRequest, NextResponse } from 'next/server';
3
4export function middleware(request: NextRequest) {
5  const environment = process.env.VERCEL_ENV;
6
7  // Nie chronij produkcji
8  if (environment === 'production') {
9    return NextResponse.next();
10  }
11
12  // Sprawdź autoryzację dla preview/staging
13  const authHeader = request.headers.get('authorization');
14  const previewToken = process.env.PREVIEW_ACCESS_TOKEN;
15
16  // Pozwól na dostęp z tokenem lub ciasteczkiem
17  const hasToken = authHeader === 'Bearer ' + previewToken;
18  const hasCookie = request.cookies.get('preview-access')?.value === previewToken;
19
20  if (!hasToken && !hasCookie) {
21    // Przekieruj na stronę logowania preview
22    return NextResponse.redirect(new URL('/preview-login', request.url));
23  }
24
25  return NextResponse.next();
26}
27
28export const config = {
29  matcher: ['/((?!preview-login|api|_next/static|favicon.ico).*)'],
30};

Deployment Hooks — automatyzacja wdrożeń

Deploy Hooks to URL-e webhooka, które wyzwalają nowe wdrożenie po wywołaniu:

1# Tworzenie Deploy Hook w Vercel:
2# Settings → Git → Deploy Hooks
3# Nazwa: "CMS Content Update"
4# Branch: main
5# → Generuje URL: https://api.vercel.com/v1/integrations/deploy/prj_xxx/yyy
6
7# Użycie z CMS (np. po publikacji artykułu):
8curl -X POST https://api.vercel.com/v1/integrations/deploy/prj_xxx/yyy
9
10# Użycie w GitHub Actions:
11# - name: Trigger Vercel Deploy
12#   run: curl -X POST ${{ secrets.VERCEL_DEPLOY_HOOK }}
13
14# Użycie z Strapi/Sanity webhook:
15# Po opublikowaniu treści → POST na Deploy Hook URL
16# → Vercel przebudowuje stronę z nowymi danymi (ISR/SSG)

Praktyczny workflow z Deploy Hooks

1// app/api/webhook/cms/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function POST(request: NextRequest) {
5  // Weryfikacja webhooka z CMS
6  const signature = request.headers.get('x-webhook-signature');
7  const secret = process.env.CMS_WEBHOOK_SECRET;
8
9  if (!verifySignature(signature, secret)) {
10    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
11  }
12
13  // Wyzwol rewalidację lub nowy deploy
14  const deployHookUrl = process.env.VERCEL_DEPLOY_HOOK;
15
16  if (deployHookUrl) {
17    await fetch(deployHookUrl, { method: 'POST' });
18    return NextResponse.json({ status: 'Deploy triggered' });
19  }
20
21  return NextResponse.json({ status: 'No deploy hook configured' });
22}
23
24function verifySignature(signature: string | null, secret: string | undefined): boolean {
25  if (!signature || !secret) return false;
26  // Implementacja weryfikacji HMAC
27  return true;
28}

Environment Promotion (dev → staging → prod)

Promocja środowisk to kontrolowany proces przenoszenia kodu między środowiskami:

1# Strategia 1: Git-flow z automatycznym deploy
2# develop → auto-deploy na dev
3# staging → auto-deploy na staging
4# main    → auto-deploy na production
5
6# Merge workflow:
7git checkout staging
8git merge develop        # Promuj dev → staging
9git push origin staging  # Auto-deploy na staging
10
11# Po testach na staging:
12git checkout main
13git merge staging        # Promuj staging → prod
14git push origin main     # Auto-deploy na production
15
16# Strategia 2: Vercel Promote (bez merge)
17# Vercel pozwala promować istniejący deployment:
18vercel promote [deployment-url] --scope=team
19
20# To przenosi DOKŁADNIE ten sam build na produkcję
21# Bez ponownego budowania — gwarancja identyczności!

Podsumowanie

Preview Deployments i środowiska staging to fundamenty profesjonalnego procesu wdrożeń:

1. Preview Deployments — automatyczne wdrożenia per PR, idealne do code review
2. Branch-based deployments — mapowanie gałęzi na środowiska (dev/staging/prod)
3. Environment promotion — kontrolowany przepływ kodu między środowiskami
4. Protected Deployments — ochrona preview i staging przed nieautoryzowanym dostępem
5. Deploy Hooks — automatyczne wyzwalanie wdrożeń z CMS lub CI/CD

W Metropolii Quantum 2150 żaden system nie przechodzi do produkcji bez pełnego cyklu preview → staging → production. To gwarantuje stabilność i jakość usług dla wszystkich mieszkańców cyberpunkowego miasta.