Operacje
Wdrożenia, migracje i dane testowe.
Staging śledzi main i stanowi bazę pełnych Railway PR Environments. Preview ma własny Postgres, konfigurację auth, pliki i integracje testowe. Migracje i seed działają w runtime, poza cache buildu.
Kolejność startu
pnpm db:migrate → pnpm db:seed → start serwera. Seed zapisuje wersję danych bez tworzenia współdzielonego hasła. Powtórzenie seeda nie usuwa danych. Reset wymaga jawnej decyzji.
Raport odbioru wiąże commit SHA, deployment ID, URL, seedVersion i zadanie Paperclip. Po nowym wdrożeniu odbiór zmienionych obszarów jest ponawiany. Zamknięcie PR sprząta środowisko, raporty GitHub Actions mają retencję 30 dni.
Worker
Jeśli produkt potrzebuje pg-boss, dodaj osobną usługę worker z tego samego commita i z tym samym DATABASE_URL. Nie łącz kolejek różnych preview. Używaj jobId i idempotencji operacji.
Granica proxy
Better Auth odczytuje adres klienta z X-Real-IP, nadpisywanego przez publiczny edge Railway. Nie wystawiaj alternatywnej, niezaufanej ścieżki do listenera, która omija ten edge. Nie stosujemy szerokiego zaufania do prywatnych CIDR proxy. Kontrakt: https://docs.railway.com/networking/public-networking/specs-and-limits.
Następny produkt
Wymagane dane: nazwa, slug, prywatne repo, oddzielny projekt Railway oraz identyfikatory projektów PostHog Production i Non-production w wybranym regionie. Wygeneruj manifest przez shipyard:init; nie nadpisuje istniejącego manifestu. Ustaw nowe sekrety bazy i auth, SHIPYARD_PRODUCT_SLUG, VITE_SHIPYARD_PRODUCT_SLUG oraz klucze telemetrii właściwego środowiska. Zmień nazwę interfejsu, instrukcje i dokumenty domenowe. Nie przenoś danych ani tokenów Shipyard Template do produktu.
Dwa tymczasowe preview można odebrać przez SHIPYARD_PREVIEW_A=https://... SHIPYARD_PREVIEW_B=https://... node scripts/check-preview-isolation.mjs. Test zakłada świeże konta i odrębne bazy oraz sprawdza brak przenoszenia danych i sesji. Tworzy wyłącznie dane syntetyczne.
Ponowny odbiór preview
Po ręcznym redeploy uruchom workflow Shipyard Preview Acceptance przez workflow_dispatch z numerem otwartego PR. Workflow pobiera bieżący SHA z GitHub i porównuje identyfikatory obu deploymentów przed i po testach. Zmiana wdrożenia w trakcie odbioru powoduje błąd. Automatyczne wyzwalanie po zdarzeniach dostawcy musi zostać sprawdzone podczas podłączania Railway GitHub App.
Playwright czyści wyłącznie swój podkatalog test-results/playwright. Raport test-results/preview.json pozostaje poza nim, aby porównanie deploymentów po E2E i raport dla QA mogły odczytać wynik sprzed testów.
Ustaw repozytoryjną zmienną SHIPYARD_RAILWAY_PROJECT_ID właściwego produktu. SHIPYARD_RAILWAY_TOKEN_TYPE to project dla tokenu środowiska albo account dla tokenu wysyłanego przez nagłówek Bearer, w tym tokenu workspace. Sekret CI nazywa się SHIPYARD_RAILWAY_TOKEN. Sprawdź możliwość odczytu metadanych PR Environments; brak zakresu blokuje odbiór.
29.10.2026 Maciej zatwierdził token całego workspace Vazco dla prywatnego repo vazco/shipyard-template, aby uprościć wdrożenie bez dodatkowej usługi. Token pozwala również zmieniać infrastrukturę wszystkich projektów workspace, choć workflow wykonuje wyłącznie odczyt. Poświadczenie jest dostępne tylko w krokach weryfikacji deploymentów z zaufanego main, poza testami aplikacji. Nie trafia do runtime agentów, usług produktu, kodu PR ani artefaktów. Dostęp do modyfikowania workflow i main wymaga niezależnego review. Kolejny produkt nie dziedziczy tej zgody ani sekretu automatycznie.
Natywny klon Railway zachowuje wartość zmiennej głównego sekretu auth, lecz aplikacja łączy ją z trwałym losowym składnikiem osobnej bazy. Nie kopiuj tabeli shipyard_auth_scope między niezależnymi środowiskami i nie resetuj jej podczas seeda. Mechanizm jest opisany w architekturze. Po wdrożeniu go do istniejącego stagingu użytkownicy logują się ponownie.
Raport CI i odbiór QA
PR powiązany z zadaniem deklaruje Paperclip-Issue: UUID w opisie. Workflow zapisuje preview.json oraz paperclip-report.json i paperclip-report.md w artefakcie shipyard-preview-evidence, z retencją 30 dni. Zmienna repo SHIPYARD_PAPERCLIP_PROJECT_ID wskazuje projekt produktu. CI nie potrzebuje klucza Paperclip.
QA pobiera artefakt wskazanego workflow, porównuje zadanie, projekt, PR, commit, oba deploymenty i działający adres, a następnie dołącza raport oraz własny werdykt do zadania w rzeczywistym kontekście swojego uruchomienia Paperclip. Zmiana commita albo deploymentu wymaga ponownego odbioru. Raport CI pozostaje w stanie awaiting_qa_review; nie zastępuje akceptacji QA ani decyzji Macieja. Przy zatrzymanej pracy agentów dowody czekają w GitHub.