GitHub Actions ile Hosting Otomatik Deploy Nasıl Yapılır? 8 Adım

GitHub Actions otomatik deploy, bir projedeki doğrulanmış değişiklikleri ana dala gönderildiğinde sunucuya kontrollü biçimde aktarmayı sağlar. Sağlıklı bir süreç yalnızca dosyaları kopyalamaz; test, erişim anahtarı, gizli değişkenler, eşzamanlı dağıtım kontrolü, doğrulama ve geri dönüş adımlarını birlikte ele alır.

Bu rehberde SSH erişimi bulunan bir Linux sunucuya rsync ile dağıtım yapan örnek bir iş akışı kuracağız. Yapı; Laravel, özel PHP projeleri ve derlenmiş statik uygulamalar için uyarlanabilir. WordPress çekirdeğini ve veritabanını bu yöntemle doğrudan dağıtmak yerine yalnızca sürüm kontrolünde tutulan özel tema veya eklenti dosyalarını hedeflemek daha güvenlidir.

GitHub Actions otomatik deploy mimarisi nasıl çalışır?

Akışın temelinde dört bileşen bulunur: kodun tutulduğu GitHub deposu, workflow’u çalıştıran GitHub runner, SSH ile erişilen hedef sunucu ve yalnızca dağıtım için kullanılan sınırlı yetkili bir kullanıcı. main dalına gönderilen değişiklik workflow’u tetikler; testler başarılı olursa yalnızca gerekli dosyalar hedef dizine aktarılır.

• Kaynak: GitHub deposundaki doğrulanmış kod
• Tetikleyici: main dalına yapılan push veya manuel çalıştırma
• Kimlik doğrulama: Parola yerine projeye özel SSH anahtarı
• Aktarım: SSH üzerinden rsync
• Koruma: GitHub Environment, secrets ve concurrency ayarları
• Kontrol: HTTP yanıtı, uygulama logları ve gerektiğinde rollback

Deployment hedefiniz paylaşımlı hosting ise önce panelden SSH erişiminin açık olduğunu ve hedef sunucuda rsync komutunun bulunduğunu doğrulayın. Yalnızca FTP sunan paketlerde aynı mantık SFTP tabanlı bir action ile kurulabilir; ancak uzaktaki komutları çalıştırmak ve atomik dağıtım yapmak daha sınırlı olur.

Kurulumdan önce alınması gereken güvenlik kararları

Workflow yazmadan önce hangi dosyaların dağıtılacağını belirleyin. .env, kullanıcı yüklemeleri, loglar, yedekler ve sunucuda üretilen önbellek dosyaları Git deposundan gelmemelidir. Bunlar release dizinlerinin dışında kalıcı bir alanda tutulmalı veya aktarım listesinden çıkarılmalıdır.

Dağıtım kullanıcısına yalnızca hedef proje dizininde yazma yetkisi verin. Root hesabını, kişisel SSH anahtarınızı veya hosting ana parolanızı GitHub’a eklemeyin. GitHub, hassas bilgilerin repository ya da environment secrets içinde saklanmasını ve workflow’a yalnızca gerektiği yerde verilmesini önerir.

1. Dağıtım için ayrı SSH anahtarı oluşturun

Anahtarı kendi bilgisayarınızda oluşturun. Aşağıdaki komut Ed25519 türünde, yalnızca bu proje için kullanılabilecek bir anahtar çifti üretir:

ssh-keygen -t ed25519 -C "github-actions-deploy" -f ./deploy_key

deploy_key.pub dosyasının içeriğini sunucudaki dağıtım kullanıcısının ~/.ssh/authorized_keys dosyasına ekleyin. Özel anahtar olan deploy_key dosyasını ise GitHub secret olarak saklayın. Özel anahtarı repoya, workflow dosyasına veya destek mesajına yapıştırmayın.

2. Hedef dizini ve izinleri hazırlayın

Sunucuda dağıtım kullanıcısıyla oturum açıp hedef dizinin varlığını ve yazma iznini kontrol edin:

ssh deploy@sunucu.example
mkdir -p /var/www/proje
test -w /var/www/proje && echo "Hedef dizin yazılabilir"

Paylaşımlı hosting ortamında hedef yol genellikle kullanıcı dizini altındadır. Yolu tahmin etmek yerine hosting panelinden veya pwd komutundan doğrulayın. Uygulamanın ihtiyaç duymadığı geniş 777 izinlerini vermeyin; dosya sahipliğini ve web sunucusu grubunu doğru ayarlamak daha güvenlidir.

3. GitHub secrets alanlarını ekleyin

Depoda Settings → Secrets and variables → Actions yolunu açın. Aşağıdaki değerleri repository secrets veya production environment secrets olarak tanımlayın:

• REMOTE_HOST: Sunucunun alan adı veya IP adresi
• REMOTE_PORT: SSH portu
• REMOTE_USER: Sınırlı yetkili dağıtım kullanıcısı
• REMOTE_PATH: Uygulamanın hedef dizini
• REMOTE_PRIVATE_KEY: Dağıtım anahtarının özel bölümü

Production için ayrı bir GitHub Environment kullanmak, secrets değerlerini yalnızca bu ortama bağlanan job’a açar. Hesabınızın planı ve depo türü destekliyorsa onay kuralı ve izin verilen branch kısıtı da ekleyebilirsiniz.

GitHub Actions ile hosting’e deploy adımları

4. Workflow dosyasını oluşturun

Depoda .github/workflows/deploy.yml dosyasını oluşturun. Aşağıdaki örnek ana dala gönderilen değişikliklerde çalışır ve gerektiğinde Actions ekranından manuel olarak da başlatılabilir:

name: Production Deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

concurrency:
  group: production-deploy
  cancel-in-progress: false

jobs:
  test-and-deploy:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      contents: read

    steps:
      - name: Kaynak kodu al
        uses: actions/checkout@v6

      - name: Proje testlerini çalıştır
        run: |
          # Bu satırı projenizin gerçek test komutuyla değiştirin.
          test -f README.md

      - name: Dosyaları rsync ile aktar
        uses: burnett01/rsync-deployments@8.0.5
        with:
          switches: -avzr --delete --exclude='.git/' --exclude='.env' --exclude='storage/' --exclude='node_modules/'
          path: ./
          remote_path: ${{ secrets.REMOTE_PATH }}
          remote_host: ${{ secrets.REMOTE_HOST }}
          remote_port: ${{ secrets.REMOTE_PORT }}
          remote_user: ${{ secrets.REMOTE_USER }}
          remote_key: ${{ secrets.REMOTE_PRIVATE_KEY }}

Örnekte kullanılan --delete, kaynakta bulunmayan dosyaları hedefte de siler. Bu seçenek eski build dosyalarını temiz tutar fakat yanlış hedef yolunda veri kaybına yol açabilir. İlk denemede ayrı bir staging dizini kullanın; kalıcı dosyaları dışlama listenize eklemeden production’da --delete çalıştırmayın.

5. Projenin gerçek test ve build komutlarını ekleyin

Örnekteki test -f README.md yalnızca workflow yapısını göstermek içindir. Laravel projesinde Composer kurulumu ve test komutu, Node.js projesinde ise paket kurulumu ve build adımı eklenmelidir. Test başarısız olduğunda deploy adımı çalışmamalıdır.

# Laravel için örnek doğrulama
composer install --no-interaction --prefer-dist
php artisan test

# Node.js tabanlı ön yüz için örnek
npm ci
npm run build

Sunucuya kaynak kod yerine derlenmiş çıktı gönderiyorsanız path değerini dist/ veya projenizin build dizini olarak değiştirin. Böylece geliştirme bağımlılıkları ve gereksiz dosyalar production ortamına taşınmaz.

6. Kalıcı dosyaları dağıtımın dışında tutun

Laravel’de .env ve kullanıcı yüklemeleri; WordPress’te wp-content/uploads; özel PHP uygulamalarında ise log ve yedek dizinleri genellikle sunucuda kalmalıdır. Bunları repodan dağıtmak, çalışma zamanında üretilen verilerin üzerine yazılmasına veya hassas ayarların açığa çıkmasına neden olabilir.

Daha güvenli bir yapı için her deploy’u tarih veya commit kimliğiyle yeni bir releases dizinine aktarabilir, kalıcı klasörleri sembolik bağlantıyla bağlayabilir ve başarılı kontrolden sonra current bağlantısını yeni release’e çevirebilirsiniz. Paylaşımlı hosting bu yapıyı desteklemiyorsa en azından düzenli yedek ve staging dizini kullanın.

7. Dağıtım sonrasında doğrulama yapın

Workflow’un yeşil görünmesi uygulamanın doğru çalıştığını tek başına kanıtlamaz. Deployment sonrasında ana URL’ye küçük bir HTTP kontrolü ekleyin ve uygulamanın loglarını inceleyin:

- name: Canlı adresi doğrula
  run: curl --fail --silent --show-error https://site.example/ > /dev/null

Giriş, form, ödeme veya yönetim paneli gibi kritik akışlar için yalnızca ana sayfa kontrolüne güvenmeyin. Staging ortamında otomatik test, production’da ise temel smoke test ve hata izleme kullanın.

8. Geri dönüş planını test edin

Rollback, hata çıktıktan sonra düşünülmemelidir. Release dizinleri kullanıyorsanız current sembolik bağlantısını önceki sürüme çevirmek hızlı bir geri dönüş sağlar. Basit rsync düzeninde ise son çalışan commit’i yeniden çalıştırabilir veya deploy öncesi alınmış yedeği geri yükleyebilirsiniz.

Veritabanı migration’ları geri dönüşü zorlaştırabilir. Geriye uyumlu migration tasarlayın, yıkıcı şema değişikliklerini ayrı aşamada uygulayın ve production migration öncesinde doğrulanmış yedek alın. Site taşıma ve sunucu değişikliklerinden sonra yapılacak kontroller için site taşıma sonrası hata kontrol listesine de göz atabilirsiniz.

GitHub Actions deploy hataları ve çözüm sırası

Permission denied (publickey)

Bu hata özel anahtarın yanlış kopyalanması, public key’in doğru kullanıcıya eklenmemesi veya .ssh izinlerinin hatalı olması nedeniyle oluşabilir. Aynı kullanıcı ve anahtarla kendi bilgisayarınızdan SSH bağlantısını test edin. Sunucuda ~/.ssh dizini için 700, authorized_keys için 600 izni yaygın güvenli ayardır.

rsync: command not found

Rsync’in hem runner hem hedef sunucu tarafında bulunması gerekir. Kullanılan action runner tarafını hazırlar; hedef sunucuda komut yoksa hosting desteğinden etkinleştirilmesini isteyin veya SFTP tabanlı bir aktarım yöntemine geçin.

Hedef dizine yazma izni yok

SSH bağlantısı başarılı olduğu halde aktarım duruyorsa REMOTE_PATH değerini ve dağıtım kullanıcısının sahipliğini kontrol edin. Sorunu chmod 777 ile gizlemek yerine hedef dizini doğru kullanıcı veya gruba bağlayın.

Deploy başarılı, site eski sürümü gösteriyor

Yanlış hedef dizini, PHP OPcache, uygulama cache’i, CDN veya tarayıcı önbelleği eski çıktıyı gösterebilir. Önce sunucudaki dosyanın commit ile gerçekten değiştiğini doğrulayın; ardından yalnızca ilgili cache katmanını temizleyin. Laravel dağıtımında kullanılan cache komutları için Laravel rehberleri, WordPress’e özel bakım adımları için WordPress rehberleri kullanılabilir.

Güvenli ve sürdürülebilir deploy kontrol listesi

• Workflow yalnızca hedef branch veya manuel tetikleyiciyle çalışıyor.
• Job izinleri contents: read gibi gereken en düşük seviyede.
• Production secrets doğrudan kaynak kodda bulunmuyor.
• Dağıtım için kişisel hesap yerine ayrı ve sınırlı kullanıcı kullanılıyor.
• Test veya build başarısız olduğunda dosya aktarımı başlamıyor.
• .env, uploads, log, yedek ve çalışma zamanı dosyaları aktarılmıyor.
• --delete seçeneği yalnızca doğrulanmış hedef dizininde kullanılıyor.
• Aynı anda iki production deploy’unu engelleyen concurrency grubu var.
• Deployment sonrasında HTTP ve kritik işlev kontrolleri yapılıyor.
• Önceki çalışan sürüme dönüş yöntemi düzenli olarak test ediliyor.

Arama motoru açısından deploy işleminin amacı yalnızca yeni kodu taşımak değildir. Yanlış yönlendirme, eksik canonical, robots.txt değişikliği veya 404 üreten asset yolları organik görünürlüğü etkileyebilir. Canlıya alma sonrasında teknik kontroller için Teknik SEO rehberleri, sunucu ve dağıtım içerikleri için Hosting kategorisi kullanılabilir.

Sık sorulan sorular

GitHub Actions ile otomatik deploy ücretli mi?

Kullanılabilen Actions süresi ve depolama kotası hesap planına ve deponun public veya private olmasına göre değişir. Sabit bir ücret varsaymak yerine GitHub hesabınızdaki güncel kullanım ve faturalandırma ekranını kontrol edin. Hedef hosting maliyeti GitHub Actions’tan ayrıdır.

FTP mi, SSH ve rsync mi kullanılmalı?

Sunucu SSH ve rsync destekliyorsa değişen dosyaları verimli aktarması, uzak komut çalıştırabilmesi ve daha ayrıntılı kontrol sunması nedeniyle rsync genellikle daha uygundur. Yalnızca FTP/SFTP erişimi bulunan hostinglerde uygun bir SFTP action kullanılabilir.

GitHub secret içindeki özel anahtar güvende mi?

Secret değerleri kaynak kodda tutulmaktan daha güvenli bir yönetim katmanı sağlar; ancak workflow’a erişen üçüncü taraf action’lar ve geniş yetkili kullanıcılar risk oluşturabilir. Ayrı deploy anahtarı kullanın, erişimi sınırlayın ve anahtarı düzenli olarak yenileyin.

WordPress sitesi GitHub Actions ile dağıtılabilir mi?

Evet; fakat veritabanı ve uploads klasörünü her deploy’da taşımak doğru değildir. Genellikle özel tema, özel eklenti veya derlenmiş varlıklar sürüm kontrolünde tutulur; kullanıcı içerikleri ve ortam ayarları sunucuda kalıcı olarak saklanır.

Production deploy öncesinde staging gerekli mi?

Zorunlu değildir ancak hedef yol, izin, cache, migration ve silme seçeneklerini production verisine dokunmadan doğrulamak için güçlü biçimde önerilir. Özellikle ilk workflow ve --delete kullanımı staging üzerinde test edilmelidir.

Sonuç

Sağlam bir GitHub Actions otomatik deploy süreci; ayrı SSH anahtarı, sınırlı kullanıcı, secrets yönetimi, test kapısı, kontrollü rsync aktarımı, doğrulama ve rollback planından oluşur. İlk kurulumu staging dizininde deneyin, kalıcı dosyaları aktarım dışında tutun ve production iş akışını yalnızca doğrulanmış branch’lere açın.

Resmî ve teknik kaynaklar

• GitHub Actions ile deployment yönetimi
• GitHub Actions secrets dokümantasyonu
• GitHub environments ve koruma kuralları
• Rsync Deployments Action kullanım sayfası