Cloudflare Worker'ı GitHub Actions ile 47 Dakikada Dağıtma Rehberi

İlk Cloudflare Worker'ınızı dağıtmak ne kadar sürecek? Cevap: sadece 47 dakika. Peki bu sürenin üç dakikasını boşa harcadığınızı fark ettiniz mi?

Neden mi? Çünkü API token izinlerinde basit ama yaygın bir hata yaptım. Bu hikaye, birçok eğitici kaynağın atladığı kritik bir ayrıntıyı ortaya koyuyor. Sadece birkaç dosya ve GitHub Actions kullanarak, projelerinizi otomatik olarak uç noktalarda (edge) yayınlamaya nasıl başlayabileceğinizi öğrenin.

Uç Noktada Basit Bir Worker Oluşturma

Gerçekten basit bir örnekle başlayalım. Projeyi anlamak yerine, dağıtım hattını (pipeline) kurmak esas amaç. Böylece gelecekteki 100 commit otomatik olarak yayınlanabilir.

İşte src/index.js dosyasındaki Worker kodu:

export default {
  async fetch(request, env, ctx) {
    return Response.json({
      message: "Edge’den selamlar",
      region: request.cf?.colo ?? "bilinmiyor",
    });
  },
};

Ve wrangler.toml yapılandırma dosyası:

name = "hello-edge"
main = "src/index.js"
compatibility_date = "2025-01-01"

Son olarak, GitHub Actions iş akışı dosyası .github/workflows/deploy.yml:

name: Worker'ı Dağıt

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Toplam üç dosya, yaklaşık 25 satır kod — boşluklar dahil. Gerçekten bu kadar basit.

Üç Dakikayı Geri Veren Hata

İlk denemede GitHub Actions 11 saniye içinde Authentication error [code: 10000] hatasıyla başarısız oldu. Token’ı yanlış kopyalamış olabileceğimi düşündüm. Token’ı yeniledim — aynı hata. Gizli adı kontrol ettim — doğru. wrangler-action README’sini iki kez okudum. Gerçeklik algım sorgulanmaya başladı.

Sonunda fark ettim: "Read All Resources" şablonunu kullanmışım. Bu token her şeyi okuyabilir, ancak hiçbir şey yazamaz. Oysa wrangler eylemi yazma iznine ihtiyaç duyar. Doğru şablon ise "Edit Cloudflare Workers" olmalıydı. Bu şablon, sadece Workers kaynağına yazma izni verir — tam olarak ihtiyaç duyulan şey.

Neden bu hata kodu bize bununla ilgili ipucu vermiyor? Çünkü hata kodu 10000, Cloudflare’ın genel kimlik doğrulama hatasıdır. "Token yazma iznine sahip değil" demiyor. Sadece "yetki geçersiz" diyor. Üç dakikanız, bir onay kutusunun eksikliğine gitti.

Başka bir yaygın tuzak: Hesap Kimliği gizli değildir. Cloudflare panosundaki URL’den doğrudan görülebilir. API token’ı ise krallığın anahtarıdır. Hem de sadece bir kez yanlışlıkla terminalde görünmesiyle bile tehlikeye atabilirsiniz. Token’ı asla commit etmeyin, loglamayın ve güvenliği ihmal etmeyin.

CI/CD’yi İlk Günden Kurmaya Değer mi?

Başta, hayır diye düşündüm. Cloudflare panosu, "Git’e Bağlan" düğmesiyle otomatik dağıtımları destekliyor — tek bir satır YAML bile yazmaya gerek yok. Basit bir Worker için bu çok daha hızlı bir yol.

Ancak ben GitHub Actions’ı tercih ettim. Sebebi: kontrol. wrangler-action yaklaşımıyla gelecekte ihtiyaç duyacağım adımları ekleyebilirim — örneğin, dağıtımdan önce testleri çalıştırmak, önce staging ortamına dağıtmak, başarısızlık durumunda Slack’e bildirim göndermek, manuel onay gerektirmek gibi.

Cloudflare’un yerleşik entegrasyonu bir kara kutu gibiyken, Actions iş akışı okunabilir bir dosya. Öğrenme projesi için bu ekstra 15 dakika kurulum, gelecekteki esneklik için iyi bir yatırım. Tek seferlik bir pazarlama sitesi içinse sadece düğmeye tıklayın yeter.

İlk Başarılı Dağıtım Anı

İş akışı bittiğinde şu log’u gördüm:

Toplam Yükleme: 0.42 KiB / gzip: 0.30 KiB
Yüklenen hello-edge (1.15 sn)
Dağıtılan hello-edge tetikleyicileri (0.32 sn)

Bağlantıya tıkladım ve Singapur veri merkezinden 38 milisaniyede yüklendiğini gördüm. Ben, Endonezya’nın Batam şehrinden çalışıyorum — yani yaklaşık 60 km öteden erişiliyor. Kodu yazan ben, 47 dakika önce yazdığım GitHub Action sayesinde, 60 km ötedeki bir sunucuda global olarak yayınlandı.

En büyük şaşkınlığım: tatmin duygusu Worker’dan değil, dağıtım hattından geldi. main branch’ine push yaptığımda GitHub’daki yeşil onay işaretini görmek ve Cloudflare panosuna hiç dokunmadan Worker’ın global olarak yayınlandığını bilmek — işte asıl kazanılan şey buydu. Worker basit bir selam mesajıydı; CI/CD ise gerçek inşa ettiğimiz şeydi.

İlk Kez Dağıtım Yapanlar İçin 3 Öneri

Eğer siz de ilk defa Cloudflare Worker’ı dağıtacaksanız, bu üç ipucuna dikkat edin:

• API token için "Edit Cloudflare Workers" şablonunu kullanın. "Read All Resources" ya da kendi oluşturduğunuz özel token’lar yerine, yerleşik şablonları tercih edin. Özel token’lar size sadece hata kodu 10000’yi kaybettirir.

• Önce dağıtım hattını kurun, sonra kodunuz ilginci olsun. İlginç bir Worker yerine, çalışan bir pipeline daha değerlidir. Pipeline ilerledikçe avantajı artar; elle yapılan dağıtımların ise hiçbir bileşik etkisi yoktur.

• Hesap Kimliği kamu, API tokenı gizlidir. Her ikisini de GitHub gizli olarak saklayabilirsiniz, ancak hangisinin önemli olduğunu bilin. Birinin sızdırılması ciddi bir riskken, diğeri sadece bir URL parçasından ibarettir.

Sıradaki Hedef: PR Başına Önizleme Dağıtımları

Şu anda Pull Request başına otomatik olarak *.workers.dev URL’si oluşturmayı hedefliyorum. Bunun için iş akışına ikinci bir job ekleyerek pull_request olayına bağlamak ve PR yorumuna önizleme linkini otomatik olarak ekleyen bir bot yazmak gerekiyor.

Eğer siz de Cloudflare Worker’larıyla (Pages değil) CI/CD kullanıyorsanız, iş akışınız nasıl? İlk deneyiminizde hangi hatadan dolayı uyarılmayı isterdiniz?

Cloudflare ekosistemindeki yenilikleri takip etmek ve gelecekteki projelerinizde otomatik dağıtım stratejilerini geliştirmek için bu adımların temelini oluşturduğunu unutmayın.