Dokümantasyon preview deployment

Dokümantasyon preview akışı iki ayrı GitHub Actions workflow’undan oluşur. PR workflow’u yalnız statik artifact üretir; Cloudflare credential’ı göremez. Trusted deploy workflow’u ise PR kaynağını çalıştırmadan bu artifact’ı doğrular ve pr-<numara> branch alias’ına yükler.

Bir defalık etkinleştirme

Cloudflare’da Git integration değil, Direct Upload türünde bir Pages projesi oluşturun ve production branch değerini main seçin. Ardından GitHub repository ayarlarına şunları ekleyin:

Yer	Ad	Değer
Repository variable	CLOUDFLARE_PAGES_PROJECT	Pages proje adı
docs-preview environment secret	CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID
docs-preview environment secret	CLOUDFLARE_API_TOKEN	Yalnız Pages Edit yetkili API token

docs-preview environment için required reviewer tanımlayın. Secret’ları repository-geneline açmayın. Variable henüz yoksa build/deploy job’ları hata vermek yerine skip olur; bu, dış kurulumun tamamlanmadığını doğru biçimde ifade eder.

PR akışı

1. Docs preview build, exact PR head SHA’yı secretsiz checkout eder.
2. make docs-preview-build, preview manifestini geçici olarak üretir ve bütün static artifact doğrulayıcılarını çalıştırır.
3. docs-preview-<run-id> artifact’ı yedi gün saklanır.
4. Başarılı run, trusted Docs preview deploy workflow’unu tetikler.
5. Deploy workflow’u default branch’teki doğrulayıcıyı checkout eder; PR kodunu checkout etmez veya çalıştırmaz.
6. Exact run artifact’ı symlink, özel dosya, boyut, release kimliği ve Git SHA açısından doğrulanır; sonra Cloudflare’a pr-<numara> olarak yüklenir.

Cloudflare hem immutable deployment URL’si hem de son commit’e ilerleyen https://pr-<numara>.<proje>.pages.dev/ alias’ı üretir. Preview artifact’ı robots.txt ile indekslemeyi reddeder; Cloudflare preview yanıtları ayrıca X-Robots-Tag: noindex taşır.

Yerel doğrulama

Temiz bir commit üzerinde şu komut provider credential’ı veya network upload’u olmadan aynı preview artifact’ını üretir:

MUNDERECAT_DOCS_PREVIEW_ID=pr-123 \
MUNDERECAT_DOCS_PREVIEW_GIT_OBJECT="$(git rev-parse HEAD)" \
MUNDERECAT_DOCS_PREVIEW_URL=https://pr-123.example.pages.dev/ \
MUNDERECAT_DOCS_CURRENT_URL=https://example.pages.dev/ \
make docs-preview-build

Komut Git SHA uyuşmazlığında veya kirli worktree’de durur. Çıktı apps/docs/dist/ altındadır; release.json seçili preview kimliğini ve exact kaynak commitini taşır.

Sorun giderme

• Job skip: CLOUDFLARE_PAGES_PROJECT repository variable’ını kontrol edin.
• Environment bekliyor: docs-preview required reviewer onayı gereklidir.
• 401/403: token’ın account kapsamını ve Cloudflare Pages Edit yetkisini kontrol edin; token değerini loglamayın.
• Artifact reddedildi: PR çıktısında _worker.js, _routes.json, _headers, _redirects, .assetsignore, functions/, symlink veya release.json kimlik sapması vardır.
• Alias uyuşmuyor: proje adı ile *.pages.dev hostunun aynı olduğundan ve branch’in pr-<numara> biçiminde deploy edildiğinden emin olun.