Dokümantasyon production deployment

Production dokümantasyonu yalnız main üzerindeki exact ve temiz bir Git commitinden üretilen statik Cloudflare Pages Direct Upload artifact’ıdır. Build, upload’dan önce bütün içerik, navigation, Pagefind, release, internal link ve statik artifact kontrollerini tamamlar.

Bir defalık kurulum

Cloudflare Pages’te production branch’i main olan Direct Upload projesi oluşturun. GitHub repository ayarlarında şu değerleri tanımlayın:

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

docs-production environment’ına required reviewer ekleyin. Credential’ları repository-geneline veya build artifact’ına koymayın. Aynı Pages projesini kullanan preview akışı ayrı docs-preview environment’ında kalır.

Artifact sözleşmesi

make docs-production-build şu iki ayrı kimlik kaydını üretir:

• release.json, mevcut dokümantasyon sürümü ve seçilebilir release’ler için canonical release sözleşmesidir;
• deployment.json, bu mutable production hedefinin exact kaynak Git commitini, public URL’sini ve development release kimliğini taşır.

Bu ayrım, henüz v1.0.0 olmayan güncel dokümantasyona sahte bir snapshot sürümü vermeden hangi kodun yayında olduğunu kesin olarak gösterir. Artifact; symlink, özel dosya, Pages Function, provider control dosyası, tekil dosya ve toplam boyut sınırı ihlalinde upload’dan önce reddedilir.

Temiz bir committe yerel production artifact’ı şu şekilde üretilebilir:

MUNDERECAT_DOCS_PRODUCTION_GIT_OBJECT="$(git rev-parse HEAD)" \
MUNDERECAT_DOCS_PRODUCTION_URL=https://munderecat-docs.pages.dev/ \
make docs-production-build

Çıktı apps/docs/dist/ altındadır. Commit uyuşmazlığı, kirli worktree, URL sapması veya release/artifact ihlali build’i durdurur.

Trusted deployment

GitHub Actions’taki Docs production deploy workflow’unu yalnız main ref’i üzerinde manuel başlatın. Job:

1. workflow’un exact github.sha commitini credentialsız checkout eder;
2. locked bağımlılıklarla production artifact’ını oluşturup doğrular;
3. protected environment credential’ıyla yalnız statik apps/docs/dist/ dizinini Pages main branch’ine yükler;
4. yayın URL’sinde bir kullanıcı sayfasını, gerçek bir internal linki ve gerçek bir Pagefind sorgusunu tek browser yolculuğunda doğrular.

Canlı smoke ayrıca release.json URL’si ile deployment.json Git commitini workflow inputlarıyla karşılaştırır. Full erişilebilirlik ve responsive browser suite’i bu deploy sırasında yeniden çalıştırılmaz.

Geri alma

Cloudflare dashboard’unda daha önce doğrulanmış immutable deployment’ı rollback hedefi seçin. Ardından smoke’u o deployment’ın kayıtlı commit ve production URL’siyle yeniden çalıştırın. Yeni bir source commit üretmeden artifact içeriğini elle düzenlemeyin veya aynı deployment kimliğinin üzerine yazmayın.

Sorun giderme

• Job skip: Workflow’un main üzerinde olduğunu ve CLOUDFLARE_PAGES_PROJECT variable’ını kontrol edin.
• Build source drift: Dispatch edilen SHA ile checkout HEAD farklıdır veya worktree kirlidir.
• Artifact reddedildi: deployment.json, release.json, indexing policy ya da statik dosya sınırlarından biri uyuşmamaktadır.
• Smoke identity hatası: Pages alias’ı henüz yeni deployment’a ilerlememiş olabilir; deployment tamamlandıktan sonra aynı komutu tekrar çalıştırın.
• Search sonucu yok: pagefind/ asset’lerinin canlı sunulduğunu ve query’nin Osmanlıca olduğunu doğrulayın.