- Katılım
- 21 May 2023
- Mesajlar
- 539
- Tepki
- 17
- Puan
- 18
Bir depoyu GitHub Pages için etkinleştirdikten sonra sitenin birkaç dakika içinde ayakta olması beklenir. Bunun yerine boş bir sayfa ya da 404 hatasıyla karşılaşmak, özellikle ilk kurulumda sık rastlanan bir durum ve genelde tek bir ayarın eksik veya yanlış olmasından kaynaklanır.
Bu yazı, yayınlanmayan bir GitHub Pages sitesinde hangi ayarların sırayla kontrol edileceğini gösteriyor.
Önce yayın kaynağını doğrulayın
GitHub'ın resmî 404 hata giderme belgesine göre yayın için kullanılan branch'in doğru seçilmiş olması gerekiyor; genelde bu ana (main) branch veya varsayılan branch. Repository ayarlarındaki Pages bölümünde hangi branch'in ve hangi klasörün (kök dizin veya /docs) yayın kaynağı olarak seçildiğini kontrol etmek ilk adım.
Aynı belge, commit'i atan kişinin repository üzerinde yönetici (admin) yetkisine sahip olması gerektiğini de belirtiyor; yetkisiz bir hesaptan yapılan push, sayfanın hiç güncellenmemesine yol açabilir.
Repository ayarlarındaki Pages ekranı, hangi kaynağın seçili olduğunu ve son yayının ne zaman/ne durumda tamamlandığını da gösteriyor. Bu ekranda bir hata işareti veya "başarısız" durumu görüyorsanız, sorun DNS'te veya dosya adında değil, build sürecinin kendisinde; bu durumda önce oradaki hata mesajını okumak zaman kazandırır.
index.html dosyasının konumu ve adı
Belgeye göre GitHub Pages, sitenizin giriş dosyası olarak bir index.html dosyası arıyor ve bu dosyanın adı büyük/küçük harfe duyarlı: Index.html şeklinde büyük I ile yazılmış bir dosya çalışmıyor. Dosyanın, seçilen yayın kaynağının en üst seviyesinde (kök dizininde veya seçtiğiniz /docs klasöründe) bulunması gerekiyor; bir alt klasörde unutulmuş index.html dosyası GitHub Pages tarafından görülmüyor.
Bu tür küçük ama belirleyici ayrıntılar, bir projeye yeni başlarken Git'in temel mantığını anlamayı da gerektiriyor; Git nedir, temel özellikleri ve kullanımı yazımız branch ve commit kavramlarının nasıl işlediğini baştan anlatıyor.
Build ayarları ve yayın kaynağı dizini
Yayın kaynağının doğru dizin olarak ayarlanması önemli; bir statik site üretici (ör. Jekyll benzeri bir araç) çıktıyı /docs klasörüne yazıyorsa ama Pages ayarı kök dizini gösteriyorsa, GitHub yanlış (veya boş) klasöre bakmaya devam eder. Bu uyumsuzluk, build'in kendisi başarılı görünse bile sitenin güncellenmemiş gibi görünmesine yol açar.
- Branch seçimi: Pages ayarlarında hangi branch'in yayınlandığı doğru mu?
- Dizin seçimi: Kök dizin mi, yoksa /docs mu seçili, build çıktısı gerçekten oraya mı yazılıyor?
- Dosya adı: index.html tam olarak bu adla, doğru harf büyüklüğünde mi?
- Custom domain / DNS: Özel bir alan adı kullanılıyorsa CNAME dosyası ve DNS kaydı tutarlı mı?
Build sürecinde önbellek kaynaklı bir tuhaflık yaşıyorsanız, yani kodu güncellediğiniz halde eski dosyanın servis edildiğini görüyorsanız, bu farklı bir teşhis konusu; GitHub Actions cache neden eski dosyayı kullanıyor yazımız bu senaryoyu ayrıca ele alıyor.
Özel alan adı kullanıyorsanız DNS tarafı
Belgeye göre özel bir domain kullanıldığında CNAME kaydının kullanıcı adınıza veya organizasyon adınıza ait "github.io" adresine işaret etmesi gerekiyor. Bu, DNS seviyesinde bir CNAME kaydı anlamına geliyor. RFC 1035'e göre CNAME kaydı, "sahibinin bir takma adı olduğu asıl adı belirten" bir kayıt türü; yani ziyaretçinin tarayıcısı sizin alan adınızı sorduğunda, DNS bu sorguyu CNAME üzerinden GitHub'ın sunucusuna yönlendiriyor.
CNAME kaydının doğru olması tek başına yeterli değil: GitHub'ın belgesi, domain değişimi sırasında sitenin otomatik olarak yeniden oluşturulmasının önerildiğini de belirtiyor; aksi halde eski ayarla üretilmiş bir sürüm servis edilmeye devam edebilir.
Bu noktada sık yapılan bir hata, CNAME dosyasını (repository köküne konan, içinde yalnızca alan adının yazılı olduğu dosyayı) DNS kaydıyla karıştırmak. Repository'deki CNAME dosyası GitHub'a hangi özel alan adının bu siteye ait olduğunu söylerken, DNS'teki CNAME kaydı tarayıcıya alan adının nereye yönlendirileceğini söylüyor; ikisi ayrı yerlerde ayarlanan iki farklı şey ve biri eksikken diğeri tek başına işe yaramıyor.
Repository görünürlüğü ve URL değişimi
Belge, repository'nin herkese açık/özel durumunun değişmesinin URL'yi etkileyebileceğini ve bunun bozuk bağlantılara yol açabileceğini not ediyor. Bir repository'yi özel yaparken veya paylaşırken bu detayı gözden kaçırmak, önceden çalışan bir Pages linkinin aniden 404 vermesine neden olabilir.
Yanlışlıkla silinen veya üzerine yazılmış bir dosyayı geri almanız gerekiyorsa bu ayrı bir Git işlemi; yanlış commit'i geri alma: revert, reset ve reflog yazımız hangi durumda hangi komutu kullanmanız gerektiğini gösteriyor.
Püf nokta' Alıntı:
Değişiklik yayına ne kadar sürede yansır
Ayarlar doğru olduğu hâlde sayfa eski hâliyle görünüyorsa, sorun yapılandırmada değil zamanlamada olabilir. Yayın işi tamamlandıktan sonra tarayıcınızın kendi önbelleği de devrede kalır; kontrolü gizli pencerede ya da önbellek atlanarak yapmak, gerçekten yayınlanıp yayınlanmadığını ayırt etmenizi sağlar.
Özetle
GitHub Pages'in yayınlanmaması genelde tek bir büyük sorundan değil, birkaç küçük ayarın (branch, dizin, dosya adı, DNS) bir aradaki uyumsuzluğundan kaynaklanıyor. Bu ayarları sırayla kontrol etmek, sorunu tahmin yürütmeden bulmanın en hızlı yolu.
Sizde son seferinde hangi ayar eksikti?
Güncelleme: 24 Ağustos 2026.
Dijital Dünyanıza Yön Veren Pusula
