GitHub Pages sınırları ve Hugo ya da Astro sitesini özel iş akışıyla yayımlamak

GitHub Pages, statik bir siteyi ücretsiz yayımlamanın en bilinen yoludur ve Hugo, Astro ya da Jekyll ile kurulmuş bir kişisel blog, portfolyo ya da belge sitesi için çoğu zaman yeterlidir. Sınırları ise belgelerde açıkça yazılı ve birkaçı tema seçimini doğrudan etkiler: yayımlanan sitenin boyutu, derlemenin süresi ve sitenin ne için kullanıldığı.

Belgelenmiş sınırlar

GitHub’ın “GitHub Pages limits” sayfasında yazanlar şunlar:

Bant genişliği ve derleme sayısı için belge “yumuşak sınır” (soft limit) ifadesini kullanıyor; boyut ve dağıtım süresi ise kesin sınır olarak yazılmış. Yumuşak sınırların aşılması hâlinde ne olacağını belgedeki ilgili bölümden okumanızı öneririz; burada belirleyici olan GitHub’ın kendi değerlendirmesidir.

Aynı sayfada bir kullanım kuralı da var: GitHub Pages, çevrim içi bir işi ya da e-ticaret sitesini çalıştırmak için ücretsiz barındırma hizmeti olarak kullanılmak üzere tasarlanmamıştır ve buna izin verilmez. Bir şirket tanıtım sitesi, ürün satan bir mağaza ya da ödeme alan bir hizmet kuracaksanız başka bir barındırma seçeneği düşünmeniz gerekir. Kişisel site, açık kaynak proje belgesi, öğrenci portfolyosu bu kuralın tipik olarak dışında kalan kullanımlardır; sınırda kalan bir durumda karar GitHub’ın kullanım şartlarına aittir.

Sınırlar tema seçimini nasıl etkiler

Boyut. 1 GB, metin ağırlıklı bir site için çok geniş bir alandır. Sorun genellikle görsellerden çıkar. Bazı temalar örnek içerikle birlikte yüksek çözünürlüklü görseller getirir; bunları kendi içeriğinizle değiştirmeden yayımlamak hem boyutu hem de sayfa hızını kötüleştirir. Hugo’nun görsel işleme özelliği ya da Astro’nun görsel bileşeni, kaynak görselden küçük sürümler üretir; bu çıktıların hepsi yayımlanan siteye eklenir. Yüzlerce görsel ve birkaç boyut seçeneği birleşince klasör hızla büyüyebilir.

Süre. 10 dakikalık dağıtım sınırı, derlemenin değil dağıtımın süresi için yazılmıştır, ama ikisi pratikte bağlantılıdır. Hugo binlerce sayfayı saniyeler içinde üretir. Astro’da derleme süresi sayfa sayısına ve kullanılan entegrasyonlara göre değişir. Jekyll büyük sitelerde belirgin biçimde yavaşlar. Derleme uzuyorsa ilk bakacağınız yer, görsel işleme ve çok sayıda etiket ya da kategori sayfası üreten tema ayarlarıdır.

Derleme sayısı. Saatte 10 derleme, her küçük düzeltmeyi ayrı bir push ile gönderen biri için dolabilir. Değişiklikleri biriktirip tek push ile göndermek bu sınırı pratikte sorun olmaktan çıkarır.

Klasik derleme ve özel iş akışı

GitHub Pages’te iki yayımlama yolu vardır. Klasik yolda GitHub, bir daldaki dosyaları kendi Jekyll ortamıyla derler. Bu yol yalnızca Jekyll içindir ve yalnızca GitHub Pages’in desteklediği eklentilerle çalışır; GitHub’ın Jekyll belgesi, desteklenmeyen eklenti kullanan siteleri GitHub Pages’in derleyemeyeceğini söyler. 20 Ekim 2026 ölçümümüzde izlediğimiz Jekyll temalarından 13 tanesinin _config.yml dosyası bu izin listesinin dışında en az bir eklenti istiyordu. Ayrıntıyı GitHub Pages’te Jekyll eklenti sınırı yazısında anlattık.

İkinci yol özel iş akışıdır (custom workflow). GitHub’ın belgesine göre bu yöntem GitHub Pages sitesinin GitHub Actions ile derlenmesini sağlar ve herhangi bir statik site üreticisiyle çalışır. Hugo ve Astro için tek seçenek budur; Jekyll için de desteklenmeyen eklentiler ya da Jekyll 4 gerektiğinde bu yola geçilir.

Özel iş akışının üç adımı

GitHub’ın belgesi iş akışını üç resmî eylem üzerinden anlatır:

1. configure-pages (actions/configure-pages): iş akışında Pages’i etkinleştirir ve site hakkında meta veri toplar.
2. upload-pages-artifact (actions/upload-pages-artifact): derlenen siteyi gzip ile sıkıştırılmış bir tar arşivi olarak paketleyip yükler. Belgeye göre arşiv 10 GB’den küçük olmalı ve sembolik ya da sabit bağlantı içermemelidir.
3. deploy-pages (actions/deploy-pages): yüklenen arşivi yayına alır. Bu iş için pages: write ve id-token: write izinleri, derleme işine bağlanan bir needs satırı ve bir ortam (varsayılan adı github-pages) gerekir.

Arada sizin derleme adımınız bulunur. Hugo için bu adım Hugo’yu kurup hugo komutunu çalıştırmak, Astro için Node.js kurup bağımlılıkları yükledikten sonra astro build çalıştırmaktır. Çıktı klasörü Hugo’da varsayılan olarak public, Astro’da dist olur; yükleme adımına bu klasörü vermeniz gerekir.

Kullanmaya başlamadan önce depo ayarlarındaki Pages bölümünde yayın kaynağını dal yerine GitHub Actions olarak seçmeniz gerekir. Belgenin bu ayarı ayrı bir sayfada anlattığını, ayar adını ise depo ekranında kontrol etmenizi öneririz.

Sürümleri sabitlemek

Özel iş akışının en büyük faydası, derleme ortamını sizin belirlemenizdir. Bunu kullanın:

• Hugo: iş akışında belirli bir Hugo sürümü ve türü (standart ya da extended) yazın. Yereldeki hugo version çıktısıyla aynı olsun. Tema Dart Sass istiyorsa Dart Sass kurulumunu da ekleyin.
• Astro: Node.js sürümünü yazın. Astro’nun kurulum belgesi en az v22.22.0 ister ve tek sayılı Node.js sürümlerini desteklemez. Depodaki kilit dosyası (package-lock, pnpm-lock, yarn.lock) hangi paket yöneticisini gösteriyorsa iş akışında da onu kullanın.
• Jekyll: Ruby sürümünü ve Gemfile.lock’u sabitleyin. Klasik derlemedeki Jekyll 3.10.0 yerine temanın istediği Jekyll 4’ü burada kullanabilirsiniz.

Bu adımları atlamanın tipik sonucu, yerelde düzgün görünen sitenin yayında farklı görünmesidir. Bir temanın hangi sürümü istediğini tema sayfalarındaki teknik kontrol listesinde gösteriyoruz; Hugo, Astro ve Jekyll listelerinden ilgili temaya geçebilirsiniz.

Özel alan adı ve Türkçe karakterli adresler

GitHub Pages özel alan adını destekler. Türkçe karakter içeren bir alan adı (ör. ı, ş, ğ içeren) DNS’te Punycode biçiminde (xn-- ile başlayan) yazılır; GitHub Pages ayarına ve DNS kaydına bu biçimi girmek, tarayıcı adres çubuğunda Türkçe görünümü bozmaz. Sayfa adreslerinde (slug) ise Türkçe karakter yerine ASCII karşılığını kullanmak paylaşılan bağlantılarda kodlanmış karakter dizilerini önler; Hugo’da removePathAccents, Astro ve Jekyll’de dosya adını ASCII seçmek bu iş içindir.

Ne zaman başka bir yer düşünmeli

• Site bir işletmenin satış ya da ödeme sitesiyse: GitHub Pages’in kullanım kuralı buna izin vermiyor.
• Aylık trafik 100 GB’ı düzenli olarak aşıyorsa: yumuşak sınır, uzun vadede sorun çıkarabilir.
• Sunucu tarafında çalışan bir şey gerekiyorsa (form işleme, oturum, Astro’nun sunucu çıktısı): GitHub Pages yalnızca statik dosya sunar.

Bu durumların dışında, bakımı süren bir tema ve sürümleri sabitlenmiş bir iş akışı ile GitHub Pages uzun süre sorunsuz çalışır. Bakımı süren temaları bakım durumu sayfasında görebilirsiniz.