GitHub’dan Netlify’ye Deploy Nasıl Yapılır? Adım Adım Rehber

GitHub Netlify deploy akışı, bir repository’yi Netlify projesine bağlayıp uygun commit ve pull request’ler için otomatik build oluşturur. Kurulumda GitHub bağlantısı yetkilendirilir, repository ve production branch seçilir, build komutu ile publish directory doğrulanır. İlk deploy tamamlandıktan sonra yeni commit’ler aynı CI/CD hattından geçer; pull request’ler ise production’dan ayrı Deploy Preview URL’lerinde incelenebilir.

Bu rehber Vite tabanlı örnek bir proje üzerinden ilerliyor. Next. js, Astro veya monorepo kullanan projelerde adapter, base directory ve output ayarları farklı olabilir. Netlify arayüzündeki düğme adları değişebilse de temel iş akışı aynıdır.

Öne Çıkanlar

• Yerel production build başarılı olmadan Git bağlantısına geçmeyin.
• Vite için tipik ayarlar npm run build ve dist olsa da proje script’leri esas alınmalıdır.
• GitHub bağlantısını yalnız gereken repository’lerle sınırlamak daha kontrollü bir yetki modeli sağlar.
• Production, Deploy Preview ve branch deploy için farklı environment values kullanılabilir.
• Build logunda kullanılan runtime, çalışma dizini ve ilk hata satırı birlikte okunmalıdır.
• Pull request preview, değişikliği merge edilmeden önce tasarım ve teknik açıdan incelemeyi kolaylaştırır.

1. GitHub Deploy İçin Proje Nasıl Hazırlanır?

GitHub Netlify deploy kurulumundan önce repository’yi temiz bir yerel kurulumla build edin:

``bash node --version npm ci npm run build ``

npm ci için güncel bir lockfile gerekir. Projeniz pnpm veya Yarn kullanıyorsa aynı package manager ve lockfile CI ortamında da kullanılmalıdır. Yerelde farklı, Netlify’da farklı package manager kullanmak dependency sürümü ve script davranışı açısından fark yaratabilir.

Vite projesindeki tipik script yapısı şöyledir:

``json { "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" } } ``

npm run build sonrasında varsayılan olarak dist klasörü oluşur. vite. config içinde build. outDir değiştirilmişse Netlify publish directory de aynı çıktıyı göstermelidir.

Repository’de kaynak kod, package manifest, lockfile ve gerekli yapılandırma bulunmalıdır. Yerel dependency klasörü, build cache’i ve gerçek environment değerleri repository’ye eklenmemelidir. Örnek . gitignore:

``gitignore node_modules/ dist/ .env .env.* !.env.example .netlify/ ``

. env. example, ihtiyaç duyulan değişken adlarını örnek değerlerle belgeler; gerçek production değeri içermez.

2. Netlify’da Repository Nasıl Seçilir?

Netlify dashboard’da yeni proje oluşturma akışından Git provider ile import seçeneğini açın ve GitHub’ı seçin. İlk bağlantıda Netlify GitHub App için izin ekranı görünür.

Yetkilendirme sırasında şu kontrolleri yapın:

1. Doğru GitHub hesabı veya organizasyon seçildi mi? 2. Yalnız gerekli repository’ler mi açıldı? 3. Organizasyon yöneticisinin approval işlemi gerekiyor mu? 4. Private organization repository desteği mevcut planı kapsıyor mu? 5. Repository adı ve default branch doğru mu?

Repository listede görünmüyorsa önce GitHub App’in repository erişimini ve organizasyon SSO politikasını kontrol edin. Farklı hesapla oturum açılması da yaygın bir nedendir.

Repository seçildikten sonra Netlify framework algılaması yapabilir. Önerilen ayarlar başlangıç noktasıdır; özel script, monorepo veya değiştirilmiş output varsa elle doğrulanmalıdır.

3. Build Command ve Publish Directory Nasıl Belirlenir?

Build command kaynak kodu dağıtılabilir çıktıya dönüştürür. Publish directory ise Netlify’nin deploy edeceği nihai dosyaları içerir.

Vite için tipik değerler:

``text Production branch: main Build command: npm run build Publish directory: dist ``

Bu değerleri üç yerde kontrol edin:

• package.json içindeki script,
• Framework yapılandırmasındaki output ayarı,
• Yerel build sonrasında gerçekten oluşan klasör.

Monorepo örneğinde base directory gerekir:

``text repository/ ├── apps/ │ └── web/ │ ├── package.json │ └── src/ ├── packages/ └── package.json ``

Uygulama apps/web içindeyse Netlify’ye doğru package/base directory verilmelidir. Workspace dependency’leri repository kökünden kuruluyorsa Netlify’nin monorepo algılaması ve package manager ayarları birlikte incelenmelidir.

Build ayarlarını version control altında tutmak için netlify. toml kullanılabilir:

``toml [build] command = "npm run build" publish = "dist" ``

UI ve dosya tabanlı ayarlarda aynı alanın farklı tanımlanması debugging’i zorlaştırabilir. Ekip olarak hangi kaynağın esas olduğunu belirleyin.

4. Environment Variables Nasıl Eklenir?

Environment variables proje ayarlarından eklenebilir ve kullanım alanına göre scope/context seçilebilir. Production, preview ve branch ortamları için farklı değerler kullanmak test ile canlı sistemi ayırır.

Deploy context	Örnek API hedefi	Önerilen veri
Production	Canlı servis	Production verisi
Deploy Preview	Sandbox servis	Sentetik veri
Branch deploy	Staging servis	Test verisi

Vite’ta VITE_ önekiyle tanımlanan değerler browser bundle’a dahil edilir. Bu nedenle yalnız ziyaretçinin görmesinde sakınca olmayan değerler bu önekle kullanılmalıdır. Sunucu tarafı erişim bilgileri Functions veya uygun server runtime’da tutulmalıdır.

Bir environment variable değiştiğinde yeni build gerekir. Önceden oluşturulan deploy dosyaları otomatik olarak yeniden yazılmaz.

5. İlk Deploy Nasıl Başlatılır?

Ayarları onayladıktan sonra Netlify repository’yi ve seçilen commit’i alır, dependency kurulumunu çalıştırır, build komutunu yürütür ve publish klasörünü deploy eder.

Logda şu satırları not edin:

• Commit SHA,
• Base directory,
• Node ve package manager sürümü,
• Install komutu,
• Build command,
• Framework/adapter algılaması,
• Publish directory,
• İlk hata veya başarı mesajı.

Yalnız son kırmızı satıra bakmayın. Build failed sonuç cümlesidir; asıl neden daha önceki Module not found, type error, eksik değişken veya bulunamayan output klasörü olabilir.

Başarılı deploy sonunda netlify. app alt alan adı oluşur. Yeni kredi tabanlı hesaplarda proje private başlayabilir; dışarıdan erişim gerekiyorsa production görünürlüğü bilinçli biçimde public yapılmalıdır.

6. İlk Canlı URL Nasıl Doğrulanır?

Production URL’sinde şu kontrolleri yapın:

• Ana sayfa HTTP 200 ile açılıyor mu?
• CSS, JavaScript, font ve görseller 404 veriyor mu?
• Browser console’da runtime hatası var mı?
• API çağrısı doğru origin’e gidiyor mu?
• İç rota adres çubuğundan doğrudan açılıyor mu?
• Mobil layout ve temel erişilebilirlik çalışıyor mu?

Header kontrolü için:

``bash curl -I https://proje-adiniz.netlify.app/ ``

Client-side router kullanan SPA’da /about doğrudan açıldığında 404 oluşabilir. Publish çıktısına _redirects dosyası eklenerek fallback tanımlanabilir:

``text /* /index.html 200 ``

Bu kural Vite SPA için yaygındır; SSR framework’lerinde adapter routing’i esas alınmalı ve aynı kural otomatik uygulanmamalıdır.

7. Yeni Commit Sonrası Otomatik Deploy Nasıl Çalışır?

Production branch’e gelen yeni commit, proje ayarına göre otomatik production deploy tetikler. Örnek branch akışı:

``bash git checkout -b update-homepage git add . git commit -m "Update homepage content" git push -u origin update-homepage ``

Pull request açıldığında Deploy Preview oluşabilir. PR merge edildiğinde production branch güncellenir ve yeni production deploy başlar. Preview ile production aynı commit’i kullansa bile URL, environment context ve erişim ayarları farklı olabilir.

Her küçük değişikliği doğrudan production branch’e göndermek basit görünür; ekiplerde review ve test kalitesini azaltabilir. Branch protection, zorunlu CI kontrolleri ve review politikası kullanmak daha izlenebilir bir akış oluşturur.

Netlify deploy’ları atomik sürümler olarak tutulur. Yeni build tamamlanmadan mevcut dosyalar parça parça değiştirilmez. Hatalı sürümde daha önce çalışan deploy yeniden yayınlanabilir. Database migration veya üçüncü taraf servisteki işlem ise kod rollback’iyle otomatik geri dönmeyebilir.

8. Deploy Preview Nasıl İncelenir?

Deploy Preview’ı yalnız “link açılıyor” testi için kullanmayın. Pull request’te şu matrisi uygulayın:

1. Preview URL’sinin doğru commit’i gösterdiğini doğrulayın. 2. UI değişikliğini mobil ve masaüstünde kontrol edin. 3. İç route’u doğrudan açın. 4. Form ve API işlemlerinin sandbox’a gittiğini doğrulayın. 5. Console ve Network hatalarını kaydedin. 6. Preview görünürlüğünü ve test verisini kontrol edin. 7. PR yorumuna test koşullarını yazın.

Preview production ile tamamen aynı olmayabilir. Domain, cookie scope, callback URL, CDN cache ve gerçek trafik davranışı farklılaşabilir. Merge sonrasında kısa production smoke test’i yapılmalıdır.

9. En Sık Build ve İzin Hataları

Repository görünmüyor

GitHub App’in repository erişimi, organizasyon approval’ı ve doğru hesapla oturum açma durumu kontrol edilmelidir.

package.json bulunamadı

Base directory yanlış olabilir. Monorepo içindeki uygulama yolu ve workspace yapısı incelenmelidir.

Build yerelde çalışıyor, Netlify’da çalışmıyor

Node sürümü, lockfile, büyük-küçük harf duyarlılığı veya eksik environment variable farklı olabilir. Yerelde temiz kurulumla aynı komutu yeniden çalıştırın.

Publish directory bulunamadı

Build tamamlanmamış, output klasörü değiştirilmiş veya path yanlış base directory’ye göre yazılmış olabilir. Logda klasörün gerçekten oluştuğunu doğrulayın.

Commit deploy başlatmıyor

Production branch, build ignore ayarı, GitHub App bağlantısı veya projenin paused durumu kontrol edilmelidir. Kredi sınırına ulaşılması da projeleri duraklatabilir.

Site güncellendi ama eski sürüm görünüyor

Yanlış preview URL’si, eski deploy linki, browser cache veya service worker etkisi olabilir. Production deploy ID ve commit SHA karşılaştırılmalıdır.

Üç Denemeli Test Planı

Briefin istediği özgün kanıt için aynı Vite repository’sinde üç koşu yapılmalıdır:

Deneme	Tetikleyici	Ölçülecekler
1	İlk repository bağlantısı	Başlangıçtan URL’ye süre, build süresi
2	Production branch commit’i	Push’tan canlıya süre, commit SHA
3	Pull request	Preview oluşma süresi, URL ve context

Ölçümde Node, npm, Vite sürümü, repository boyutu, cache durumu ve ağ koşulu belirtilmelidir. İlk build ile cache’li ikinci build doğrudan karşılaştırılmamalıdır.

> Editör notu — zorunlu özgün test: Bu taslak hazırlanırken yeni GitHub repository’si Netlify hesabına bağlanmadı ve üç süre denemesi yapılmadı. Yayından önce temiz bir Vite projesiyle üç bağımsız koşu yapılmalı; sürümler, commit SHA’lar, cache durumu ve log zaman damgaları kaydedilmelidir. Ölçülmemiş süreler yazıya eklenmemelidir.

> Görsel notu: GitHub App izni, repository seçimi, build settings, deploy logu, Deploy Preview ve production URL ekranlarından numaralı seri hazırlanmalıdır. Kişisel ve organizasyon bilgileri maskelenmelidir.

> İç link editör notu: Deploy Previews, Netlify CLI ve netlify. toml rehberleri yayımlandığında ilgili bölümlere bağlantı eklenmelidir.

GitHub Netlify Deploy Kontrol Listesi

• [ ] Temiz yerel production build başarılı.
• [ ] Package manager ve lockfile tutarlı.
• [ ] GitHub App yalnız gereken repository’lere erişiyor.
• [ ] Production branch doğru.
• [ ] Base directory, build command ve publish directory doğrulandı.
• [ ] Production ve preview environment değerleri ayrıldı.
• [ ] Pull request preview incelendi.
• [ ] İç route, form, API ve asset’ler test edildi.
• [ ] Production görünürlüğü bilinçli seçildi.
• [ ] Rollback sahibi ve kullanım bildirimleri belli.

Sık Sorulan Sorular

GitHub repository public olmak zorunda mı?

Hayır. Private repository bağlanabilir; organization-owned private repo desteği plan ve GitHub yetkilerine göre değişebilir.

Her commit production deploy oluşturur mu?

Production branch’e gelen ve ignore kuralına takılmayan commit genellikle production deploy tetikler. Pull request ve başka branch’ler preview veya branch deploy oluşturabilir.

GitHub Actions gerekli mi?

Temel continuous deployment için Netlify’nin Git entegrasyonu yeterli olabilir. Özel test, güvenlik taraması veya çok platformlu pipeline gerekiyorsa GitHub Actions eklenebilir.

Hatalı deploy nasıl geri alınır?

Daha önce çalışan production deploy dashboard’dan yeniden yayınlanabilir. Uygulamanın veri veya dış servis değişiklikleri ayrıca değerlendirilmelidir.

Build ayarları UI’da mı, netlify.toml içinde mi tutulmalı?

Küçük denemede UI hızlıdır. Ekipli projede kritik ayarları version control altında tutmak değişiklik geçmişini görünür kılar. Aynı değeri iki yerde çelişkili tanımlamayın.

Kaynaklar

• Add a new project
• Deploy overview
• Build configuration
• Deploy Previews
• Environment variables
• Vite on Netlify

Sonuç

GitHub Netlify deploy akışı, repository bağlantısından sonra build, preview ve production süreçlerini commit geçmişiyle izlenebilir hâle getirir. Sağlam kurulum için doğru repository’yi seçmek yetmez: temiz build’i doğrulayın, doğru base ve publish dizinini kullanın, environment context’lerini ayırın, Deploy Preview’da gerçek test yapın ve build logundaki ilk hatadan ilerleyin. Bu yapı, manuel klasör yüklemeye göre daha sürdürülebilir bir yayın hattı sunar.

GitHub deponuzla bu deploy akışını denemek için [ücretsiz Netlify hesabı oluşturabilirsiniz](https://join. netlify. com/wmkqymu1heo2). Bu bir iş ortaklığı bağlantısıdır; bağlantı üzerinden kayıt olmanız veya ücretli plana geçmeniz halinde Ortak Alan komisyon kazanabilir.