GitHub Pages: siteniz için ücretsiz barındırma, adım adım nasıl yayınlanır

GitHub Pages nedir

GitHub Pages, GitHub'a entegre, ücretsiz bir statik site barındırma hizmetidir. Sitenizin dosyalarını normal bir Git repository'sinde tutarsınız; GitHub bunları HTTPS üzerinden sunar. Doğru dala yapılan her git push siteyi günceller, bu yüzden ayrı bir FTP'ye, barındırma paneline veya elle dosya yüklemeye gerek yoktur.

Hizmet farklı adlarla aranır: «github pages», «github pages nedir», bazen de «github hosting». Doğru ad GitHub Pages'tir: bu, Git'in değil GitHub platformunun bir özelliğidir. Git'in kendisi hiçbir şey yayımlamaz, yalnızca değişikliklerin geçmişini tutar.

GitHub Pages'te en çok proje dokümantasyonları, kişisel sayfalar ve portföyler, bloglar, tanıtım sayfaları, eğitim projeleri ve React, Vue veya Svelte ile geliştirilmiş, derlendikten sonra yayınlanan ön yüz demoları yayınlanır.

GitHub Pages statik içerik barındırır

Anahtar kelime statiktir. GitHub Pages tarayıcıya hazır dosyaları sunar: HTML, CSS, JavaScript, görseller, yazı tipleri, JSON. Sunucu tarafında kod çalıştırmaz: PHP, Python veya Node.js ile sunucu tarafı kod ve veritabanları burada çalışmaz. Sitenizde kayıt, sepet veya veritabanlı bir yönetim paneli gerekiyorsa geleneksel bir barındırma hizmeti ya da bulut platformu gerekir.

Tarayıcıdaki JavaScript ise normal şekilde çalışır. Tek sayfalık bir uygulama dış API'lere istek atabilir, formlar üçüncü taraf servisler üzerinden gönderilebilir ve site içi arama istemci tarafında yapılabilir.

GitHub Pages'te hangi tür siteler yayınlanır

GitHub Pages'te üç tür site vardır ve türü adresi belirler.

Hesap başına yalnızca bir kullanıcı veya organizasyon sitesi olabilir, proje siteleri ise repository başına bir tane olmak üzere sınırsızdır. Kişisel site repository'sinin adı GitHub kullanıcı adınızla birebir aynı olmalıdır: kullanıcı adınız ali-yilmaz ise repository ali-yilmaz.github.io adını taşır.

Herkese açık repository'ler için Pages ücretsiz pakette kullanılabilir. Özel bir repository'den site yayınlamak GitHub'ın ücretli planlarını gerektirir; yayınlanan site ise yine de internette herkese açıktır.

GitHub Pages'te site adım adım nasıl yayınlanır

En basit yolu inceleyelim: hazır HTML dosyaları, bir dal üzerinden yayın. Bir GitHub hesabı ve kurulu Git gerekir.

Adım 1. Repository oluşturun

GitHub'da yeni bir herkese açık repository oluşturun. Kişisel site için adı username.github.io olmalıdır; proje sitesi için ad serbesttir. Ardından klonlayın ve ana sayfayı ekleyin:

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Merhaba, GitHub Pages</h1>" > index.html

Ana sayfa mutlaka index.html olarak adlandırılmalıdır (ya da index.md veya README.md: GitHub bunları da ana sayfaya dönüştürür). Büyük-küçük harf önemlidir: Index.html çalışmaz.

Adım 2. Dosyaları GitHub'a gönderin

git add index.html
git commit -m "Sitenin ilk sayfası"
git push origin main

Değişiklikleri ilk kez gönderiyorsanız ve Git kullanıcı adı ile parola istiyorsa, kişisel bir erişim token'ı veya tarayıcıyla giriş kullanın: GitHub hesap parolanızı HTTPS üzerinden git push için kabul etmez.

Adım 3. Ayarlardan Pages'i etkinleştirin

Repository'yi GitHub'da açın, Settings'e gidin ve yan menüden Pages'i seçin. Build and deployment bloğunda Source alanından Deploy from a branch seçeneğini işaretleyin. Altında dalı (genellikle main) ve klasörü belirtin: kök / (root) ya da /docs. Save düğmesine basın.

Klasör /docs seçeneği, repository'de proje kodu varken dokümantasyon sitesini ayrı bir klasörde tutmak istediğinizde kullanışlıdır.

Adım 4. Yayınlanmasını bekleyin

Yayınlama birkaç saniyeden birkaç dakikaya kadar sürer; GitHub ilk yayının 10 dakikaya kadar sürebileceği konusunda uyarır. Derleme sürecini Actions sekmesinde görebilirsiniz: pages build and deployment adlı bir iş belirir. Yeşil onay işaretiyle tamamlandığında Settings → Pages sayfasında sitenin adresi görünür.

Bundan sonra yapacağınız şey basit: dosyaları düzenleyin, commit yapın ve git push edin; site kendiliğinden güncellenir.

GitHub Actions ile yayınlama

Dal üzerinden yayınlama, repository'de hazır dosyalar olduğunda uygundur. Ancak site önce derlenmeliyse (örneğin Vite, React ya da Hugo gibi bir üreticiyle hazırlanmış bir uygulama), GitHub Actions kaynağı daha uygundur. Settings → Pages'te Source alanından GitHub Actions'ı seçin; GitHub hazır iş akışı şablonları önerir.

Derlemeden sonra dist klasöründeki statik dosyaları yayınlayan minimal bir iş akışı şöyledir:

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

Dosya .github/workflows/pages.yml yoluna kaydedilir. git push'tan sonra Actions bağımlılıkları kurar, projeyi derler ve dist içeriğini yayınlar. Bu yaklaşımın avantajı, repository'de yalnızca kaynak kodun bulunması ve derlenmiş dosyaların commit geçmişini şişirmemesidir.

Proje sitelerinde sık yapılan bir hata yollarla ilgilidir. Site /repository-adi/ adresinde açılır, ama derleyiciler varsayılan olarak kaynakları / kökünden çağırır. Sonuçta sayfa stilsiz ve komutsuz yüklenir. Bu, temel yolu ayarlayarak çözülür: Vite'ta base: '/repository-adi/' parametresiyle, diğer derleyicilerde benzer bir seçenekle.

Jekyll ve statik site üreticileri

Dal üzerinden yayınlamada GitHub, dosyaları varsayılan olarak Ruby ile yazılmış bir statik site üreticisi olan Jekyll'den geçirir. Bu sayede sayfaları Markdown ile yazabilir, temalar ve şablonlar kullanabilirsiniz; GitHub bunları HTML'e çevirir. Blog veya dokümantasyon için bu pratiktir: .md dosyalarını yazarsınız, görünümü tema halleder.

Yan etkisi: Jekyll, adı alt çizgiyle başlayan dosya ve klasörleri yok sayar, örneğin _next veya _assets. Site başka bir araçla derlenmişse ve bu klasörlere ihtiyacınız varsa, kök dizine boş bir .nojekyll dosyası koyun:

touch .nojekyll
git add .nojekyll
git commit -m "Jekyll'i devre dışı bırak"
git push

Hugo, Astro, Eleventy, MkDocs veya Docusaurus gibi diğer üreticiler GitHub Actions üzerinden çalışır: derleme iş akışında yapılır, son klasör yayınlanır. GitHub Pages bu araçları tanımaz, yalnızca son dosyalara ihtiyaç duyar.

GitHub Pages'e kendi alan adınızı bağlama

username.github.io adresi eğitim projeleri için uygundur, ama portföy veya proje için kendi alan adınız daha iyidir. Bağlantı iki yönlüdür: alan adı sağlayıcınızda ve repository ayarlarında.

DNS yapılandırması

www.example.com ya da blog.example.com gibi bir alt alan adı için username.github.io'ya işaret eden bir CNAME kaydı oluşturun. Kök alan adı example.com için GitHub Pages IP adreslerine A kayıtları ekleyin:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

AAAA kayıtları için IPv6 dâhil güncel liste GitHub dokümantasyonundadır; kurulumdan önce oradan doğrulayın. Hem kök alan adını hem www alt alan adını ayarlamak iyi olur: böylece GitHub birinden diğerine yönlendirme yapar.

Repository ayarları

Settings → Pages'te alan adınızı Custom domain alanına yazın ve kaydedin. Dal üzerinden yayınlıyorsanız GitHub, repository'de alan adınızı içeren bir CNAME dosyası oluşturur. Actions ile yayınlarken CNAME dosyasına gerek yoktur; alan adı ayarlarda tutulur.

GitHub, hesap ayarlarınızdaki Pages bölümünden alan adınızı doğrulamanızı önerir: DNS GitHub'a işaret ederken başka birinin alan adınızı kendi repository'sine bağlamasını önler. DNS değişiklikleri bir güne kadar yayılabilir; alan adı hemen çalışmazsa bekleyin.

GitHub Pages'te HTTPS

*.github.io adresleri için HTTPS her zaman açıktır. Kendi alan adınız için DNS doğru yapılandırıldığında GitHub, Let's Encrypt sertifikasını kendisi düzenler. Bundan sonra Settings → Pages'te Enforce HTTPS kutusu görünür: işaretleyin, böylece tüm HTTP istekleri HTTPS'e yönlendirilir.

Kutu pasifse sertifika henüz düzenlenmemiştir: DNS kayıtlarını kontrol edin ve bekleyin. Bazen Custom domain alanındaki alan adını silip yeniden eklemek yardımcı olur; bu yeni bir sertifika düzenlemesini tetikler. Ayrıca sitenizin görsel veya script'leri http:// üzerinden yüklemediğinden emin olun: tarayıcı bunları karışık içerik olarak engeller.

GitHub Pages'in sınırları

Barındırma ücretsizdir, ama sınırları vardır. Bunlar GitHub dokümantasyonunda yazılıdır ve çoğu kişisel veya eğitim sitesi için fazlasıyla yeterlidir.

Teknik sınırların yanında kullanım kuralları da vardır: GitHub Pages online mağazalar veya SaaS gibi ticari servisler için tasarlanmamıştır; büyük dosyaların dağıtımı için de uygun değildir. Portföy, dokümantasyon, blog ve proje tanıtım sayfası için mükemmeldir.

Bir diğer sınır, sunucu tarafı yapılandırmanın olmamasıdır. Kendi yönlendirmelerinizi, yanıt başlıklarınızı veya .htaccess benzeri kurallarınızı ekleyemezsiniz. Kök dizine yalnızca kendi 404.html sayfanızı koyabilirsiniz: GitHub bunu var olmayan adresler için gösterir.

Sık karşılaşılan sorunlar ve çözümleri

GitHub Pages'te 404 hatası

En yaygın neden, kaynak olarak seçilen klasörde index.html dosyasının bulunmamasıdır. Doğru dalı ve klasörü (/ (root) veya /docs) seçtiğinizi ve dosyanın tam olarak küçük harflerle index.html adını taşıdığını kontrol edin. İkinci neden, sitenin henüz yayınlanmamış olmasıdır: Actions sekmesine bakın ve derlemenin bitmesini bekleyin.

404, tek sayfalık bir uygulamanın iç sayfalarında sayfa yenilendiğinde çıkıyorsa, sorun yönlendirmededir: sunucu /about adresini tanımaz, çünkü böyle bir dosya yoktur. Geçici çözümler hash yönlendirmesi (/#/about) veya index.html dosyasının 404.html adıyla bir kopyasıdır.

Site güncellenmiyor

Önce değişikliklerin gerçekten GitHub'a ulaştığını doğrulayın: git status ve git log origin/main --oneline -3 komutlarını çalıştırın. Sonra Actions sekmesini açın: derleme başarısız olduysa kırmızı bir çarpı ve hatayı gösteren bir günlük görürsünüz; örneğin bir Jekyll dosyasındaki sözdizimi hatası ya da iş akışındaki bir sorun.

Derleme başarılı olmuşsa ama tarayıcıda eski sürümü görüyorsanız, suç önbelleğe aittir. GitHub Pages dosyaları birkaç dakika önbellekte tutar, tarayıcı da kendi önbelleğini kullanır. Sayfayı önbelleği temizleyerek yenileyin (Ctrl+F5 veya Cmd+Shift+R) ya da gizli pencerede açın.

Stiller ve görseller yüklenmiyor

Neredeyse her zaman yollar yanlıştır. Proje sitesinde /style.css bağlantısı, repository klasörüne değil username.github.io köküne gider. Göreli yollar kullanın (style.css, ./img/logo.png) ya da derleyicide temel yolu ayarlayın. Ayrıca adların büyük-küçük harfini kontrol edin: GitHub sunucuları Logo.PNG ile logo.png'yi ayırt eder; Windows'ta yerelde her şey çalışıyor olsa bile.

Alt çizgili klasörler kayboldu

Bu Jekyll'dir: _app gibi klasörleri yayımlamaz. Kök dizine .nojekyll dosyası ekleyin ya da GitHub Actions üzerinden yayınlamaya geçin.

Sonuç

GitHub Pages, statik bir siteyi ücretsiz yayınlamanın en hızlı yoludur: bir repository, bir index.html dosyası, Settings → Pages'te kaynak ayarı ve birkaç dakika sonra site username.github.io adresinde açılır. Derlenmesi gereken siteler için GitHub Actions, kendi alan adınız için DNS kayıtları ve Enforce HTTPS kutusunu kullanın. Sınırları unutmayın: yalnızca statik içerik, sunucu tarafı kod yok ve boyut ile trafik limitleri var. GitHub ile çalışma, değişiklik gönderme ve otomasyon Git kursunda uygulamalı olarak ele alınmaktadır.