GitHub Pages ile ücretsiz site yayınlamak: adım adım

Kişisel bir site, bir portföy ya da bir projenin tanıtım sayfası için ayrı bir hosting hizmetine gerek yok. Kodun zaten GitHub'daysa, GitHub Pages ile birkaç dakikada yayına alabilirsin. Bu yazı ücretsiz yayın serimizin ilk adım adım rehberi.

Ne zaman GitHub Pages?

GitHub Pages yalnızca statik dosyaları yayınlıyor: HTML, CSS, JavaScript, görseller. Sunucuda kod çalıştırmıyor, veritabanı da yok. Yani düz bir HTML sitesi, Vite ile derlenmiş bir React ya da Vue arayüzü, Astro veya Hugo ile üretilmiş bir site için uygun; bir API ya da Next.js'in sunucu özellikleri için uygun değil. Resmî sınırlar: site en fazla 1 GB, ayda 100 GB'lık esnek trafik sınırı ve ticari bir iş için kullanılmaması.

İki tür site

• Kullanıcı sitesi: Depo adı tam olarak kullaniciadin.github.io olmalı. Site https://kullaniciadin.github.io adresinde açılıyor. Her hesabın bir tane.
• Proje sitesi: Herhangi bir depodan yayınlanıyor ve https://kullaniciadin.github.io/depo-adi adresinde açılıyor. İstediğin kadar olabilir.

Yol 1: düz HTML, branch'ten yayın

Elinde derleme gerektirmeyen bir index.html varsa en kısa yol bu:

1. Dosyalarını deponun köküne koy ve main'e push et. Ana sayfanın adı index.html olmalı.
2. Depoda Settings → Pages bölümünü aç.
3. Build and deployment altında kaynak olarak Deploy from a branch'i seç.
4. Branch olarak main, klasör olarak / (root) seç ve kaydet.
5. Bir iki dakika sonra sayfanın üstünde sitenin adresi görünüyor.

Bundan sonra main'e her push'ta site kendiliğinden güncelleniyor.

Yol 2: derlenen projeler, GitHub Actions ile

Vite, Astro ya da benzeri bir araçla yazdığın bir projenin önce derlenmesi gerekiyor. Bunun için kaynağı GitHub Actions olarak seç ve deponun içine bir iş akışı ekle. Örneğin Vite ile yazılmış bir proje için .github/workflows/pages.yml:

name: 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: 22
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

Settings → Pages bölümünde GitHub'ın hazır iş akışı önerileri de var; kendi aracına uyanı seçip oradan başlayabilirsin. Kullandığın eylemlerin güncel sürümlerini GitHub'ın belgelerinden kontrol et.

Proje sitesinde yol sorunu

Proje siten /depo-adi altında açıldığı için, varsayılan ayarlarla derlenen bir Vite projesinde CSS ve JavaScript dosyaları bulunamaz ve sayfa boş görünür. Çözüm, vite.config dosyasında temel yolu belirtmek:

export default defineConfig({
  base: "/depo-adi/",
});

Tek sayfalık bir React uygulamasında yönlendirme (React Router) kullanıyorsan, alt sayfaları doğrudan açınca 404 alabilirsin; çünkü GitHub Pages yalnızca var olan dosyaları sunuyor. Bu durumda hash tabanlı yönlendirme kullanmak en basit çözüm.

Kendi alan adın

1. Settings → Pages → Custom domain alanına alan adını yaz (örneğin adsoyad.dev).
2. Alan adını aldığın yerin DNS ayarlarında, ana alan adı için GitHub'ın IP adreslerine işaret eden A kayıtlarını, www için de kullaniciadin.github.io'ya işaret eden bir CNAME kaydını ekle. Güncel IP adresleri GitHub'ın alan adı belgesinde yazıyor.
3. DNS yayıldıktan sonra aynı sayfada Enforce HTTPS kutusunu işaretle.

Kontrol listesi

• Ana sayfanın adı index.html mi?
• Derlenen projede çıktı klasörü (dist, build) iş akışındaki yol ile aynı mı?
• Proje sitesinde temel yol (base) ayarlandı mı?
• Actions sekmesinde iş akışı yeşil mi? Kırmızıysa hata mesajı orada.

Serinin diğer yazılarında Vercel, Netlify ve Render'ı anlatıyoruz. Hangisini ne zaman seçeceğini merak ediyorsan önce seri giriş yazımıza bak. Takıldığın bir yer olursa re:make her pazar 15.00'te Buca'da buluşuyor; üye olmadan da gelebilirsin. Yeri ve saati burada.