GitHub Actions Self-Hosted Runner Yapılandırması: Özelleştirilmiş CI/CD Ortamları Oluşturma

8 Eylül 2026 · Gökhan Güngör

GitHub Actions Self-Hosted Runner Yapılandırması: Özelleştirilmiş CI/CD Ortamları Oluşturma

GitHub Actions, modern yazılım geliştirme süreçlerinin merkezinde yer alarak otomasyonu kolaylaştırır. Ancak bazı durumlarda, GitHub'ın sağladığı "hosted runner"lar belirli gereksinimleri karşılamakta yetersiz kalabilir. Bu noktada, kendi altyapımızda barındırdığımız "self-hosted runner"lar devreye girer. Bu makale, bir GitHub Actions self-hosted runner'ın nasıl kurulacağını, yapılandırılacağını ve üretim ortamlarında nasıl etkili bir şekilde kullanılacağını derinlemesine inceleyecektir.

Neden Self-Hosted Runner Kullanmalısınız?

Self-hosted runner'lar, standart GitHub hosted runner'ların ötesinde bir dizi avantaj sunar:

Özelleştirilmiş Ortamlar: Belirli donanım gereksinimleri (GPU'lar, yüksek RAM/CPU), özel yazılımlar veya işletim sistemleri gerektiren iş yükleri için idealdir. Örneğin, makine öğrenimi modellerini eğitmek veya özel derleyici zincirleri kullanmak.
Güvenlik ve Ağ Kontrolü: Şirket içi ağ kaynaklarına (veritabanları, dahili API'ler) erişim gerektiren veya hassas verilerin GitHub'ın dışına çıkmasını istemediğiniz senaryolarda, runner'ınızı izole bir ağda barındırabilirsiniz.
Maliyet Optimizasyonu: Özellikle uzun süren veya yüksek frekanslı CI/CD iş yükleri için, kendi altyapınızda (örneğin, mevcut sunucularınızda veya AWS Spot/Reserved Instances üzerinde) runner çalıştırmak, GitHub'ın dakika bazlı faturalandırmasına göre daha ekonomik olabilir.

Self-Hosted Runner Kurulum Adımları (Linux Örneği)

Bir Linux makinesi üzerinde self-hosted runner yapılandırma süreci aşağıdaki adımları içerir. Bu adımlar, genel bir Linux dağıtımı (Ubuntu/CentOS) için geçerlidir.

Adım 1: Ön Hazırlıklar ve Bağımlılıklar

İlk olarak, runner yazılımının çalışabilmesi için gerekli bağımlılıkları yüklememiz gerekir. `curl` ve `git` genellikle varsayılan olarak bulunur, ancak emin olmak için kontrol edebilir veya yükleyebilirsiniz. Docker gerektiren iş yükleri için Docker'ı da kurmalısınız.

sudo apt update
sudo apt install -y curl git docker.io # Debian/Ubuntu
# Veya CentOS/RHEL için:
# sudo yum update -y
# sudo yum install -y curl git docker
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER # İsteğe bağlı, mevcut kullanıcıya docker yetkisi verir

Bu komutlar, sisteminizi günceller, gerekli paketleri kurar ve Docker servisini başlatır. `usermod` komutu, Docker komutlarını `sudo` kullanmadan çalıştırmak için geçerli kullanıcıya Docker grubunu ekler. Değişikliklerin etkili olması için oturumu yeniden başlatmanız gerekebilir.

Adım 2: Runner Yazılımını İndirme ve Çıkarma

GitHub Actions runner yazılımını indirmek ve uygun bir dizine çıkarmak için aşağıdaki komutları kullanın. Genellikle `/actions-runner` gibi bir dizin tercih edilir.

mkdir ~/actions-runner && cd ~/actions-runner
curl -o actions-runner-linux-x64-2.308.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.308.0/actions-runner-linux-x64-2.308.0.tar.gz
tar xzf ./actions-runner-linux-x64-2.308.0.tar.gz

Burada, `~/actions-runner` adında bir dizin oluşturulur, GitHub'dan en güncel runner sürümü indirilir ve ardından sıkıştırılmış dosya bu dizine açılır. Sürüm numarasını güncel tutmak önemlidir.

Adım 3: Runner'ı GitHub'a Kaydetme

Runner'ı bir GitHub deposuna veya organizasyonuna kaydetmek için bir konfigürasyon betiği çalıştırılması gerekir. Bu betik, runner'ın kimliğini doğrulamak için bir token'a ihtiyaç duyar.

GitHub arayüzünde (repo/organizasyonunuzun `Settings -> Actions -> Runners` bölümünden) "New self-hosted runner" butonuna tıklayarak geçici bir kayıt token'ı alabilirsiniz.

./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN
# Veya organizasyon seviyesinde:
# ./config.sh --url https://github.com/YOUR_ORG --token YOUR_TOKEN

`YOUR_ORG/YOUR_REPO` kısmını kendi depo veya organizasyon URL'inizle, `YOUR_TOKEN` kısmını ise GitHub'dan aldığınız token ile değiştirmelisiniz. Betik, runner'a bir isim vermenizi ve etiketler (label) tanımlamanızı isteyecektir. Etiketler, iş akışlarınızda belirli runner'ları hedeflemek için kullanılır (örneğin, `self-hosted, linux, x64, my-custom-gpu-runner`).

Adım 4: Runner Servisini Başlatma

Runner'ı sürekli çalışır durumda tutmak ve makine yeniden başlatıldığında otomatik olarak başlamasını sağlamak için bir sistem servisi olarak yapılandırmak en iyi yaklaşımdır. `systemd` kullanan Linux sistemlerinde bu şu şekilde yapılabilir:

`actions-runner` dizininde `svc.sh install` komutunu çalıştırın:

sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

Bu komutlar, runner'ı bir `systemd` servisi olarak kurar, başlatır ve durumunu kontrol eder. Artık runner'ınız GitHub'da "online" olarak görünecek ve işleri kabul etmeye hazır olacaktır.

Üretim Ortamı Senaryoları ve Dikkat Edilmesi Gerekenler

Self-hosted runner'lar, karmaşık ve özelleşmiş CI/CD ihtiyaçlarını karşılamak için güçlü araçlardır. İşte bazı gerçek dünya senaryoları:

Senaryo 1: GPU Destekli Makine Öğrenimi İş Yükleri

Bir AI/ML ekibi, büyük veri kümeleri üzerinde makine öğrenimi modellerini eğitmek için GitHub Actions kullanmak istemektedir. Bu eğitim süreci, yüksek performanslı GPU'lara sahip makineler gerektirir. GitHub'ın hosted runner'ları bu tür spesifik donanımı sağlamadığı için, ekip kendi NVIDIA GPU'larına sahip bir AWS EC2 P3/P4 instance'ı üzerinde bir self-hosted runner yapılandırır. Runner'a `gpu-runner` etiketi atanır.

GitHub Actions iş akışı (workflow) bu runner'ı hedeflemek için `runs-on` anahtar kelimesini kullanır:

name: Train ML Model

on: [push]

jobs:
  train:
    runs-on: [self-hosted, linux, x64, gpu-runner]
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Train model
        run: python train_model.py --gpus 1

Bu yapılandırma, sadece `gpu-runner` etiketine sahip self-hosted runner'ların bu işi yürütmesini sağlar, böylece pahalı GPU kaynakları sadece gerektiğinde kullanılır ve iş yükü doğru donanımda çalışır.

Senaryo 2: İç Ağ Kaynaklarına Güvenli Erişim

Bir finansal teknoloji şirketi, dağıtılmış bir uygulamanın entegrasyon testlerini çalıştırmak istemektedir. Bu testler, şirket içi ağda bulunan bir test veritabanına ve bazı dahili API'lere erişim gerektirmektedir. Güvenlik politikaları gereği, bu kaynaklara sadece belirli IP aralıklarından ve şirket içi ağdan erişim sağlanabilir.

Şirket, kendi veri merkezindeki veya AWS VPC'sindeki özel bir subnet içinde, ağ erişim politikalarıyla sıkı bir şekilde korunan bir sunucu üzerinde self-hosted runner'lar kurar. Bu runner'lar, gerekli ağ bağlantılarına sahip olacak şekilde yapılandırılır ve böylece hassas test verilerinin dışarı sızması riski minimize edilir. Runner'lar, dışarıdan erişilemeyen iç kaynaklara güvenli bir köprü görevi görür.

Senaryo 3: Dinamik Olarak Ölçeklenen Runner Filoları (AWS ASG ile)

Büyük bir yazılım şirketi, günde yüzlerce CI/CD işi çalıştıran monorepo yapısına sahiptir. Sabit sayıda self-hosted runner, yoğun zamanlarda darboğaz oluştururken, az yoğun zamanlarda kaynak israfına neden olmaktadır.

Bu sorun, AWS Auto Scaling Group (ASG) kullanarak dinamik olarak ölçeklenen bir runner filosu ile çözülebilir. Şirket, bir EC2 Launch Template oluşturur. Bu template, runner yazılımını indiren, yapılandıran ve GitHub'a kaydeden bir `user-data` betiği içerir. ASG, CloudWatch metriklerine (örneğin, bekleyen iş sayısı) göre EC2 instance'larını otomatik olarak başlatır ve sonlandırır. GitHub'dan yeni bir iş geldiğinde, ASG yeni bir EC2 instance'ı başlatır, bu instance kendini runner olarak kaydeder, işi yürütür ve iş bittiğinde `lifecycle hooks` veya özel bir `cleanup` betiği ile kendini GitHub'dan kaldırır ve sonlandırır. Bu, maliyetleri önemli ölçüde optimize ederken, her zaman yeterli kapasite sağlar.

Güvenlik Perspektifi

Self-hosted runner'lar, çalıştıkları makine üzerinde tam kontrole sahip oldukları için güvenlik açıkları potansiyeli taşır.

Yetki Yönetimi: Runner'ın GitHub Actions token'ının sadece gerekli minimum yetkilere sahip olduğundan emin olun (Least Privilege Prensibi).
Ağ İzolasyonu: Runner'ı mümkün olduğunca izole bir ağ segmentinde tutun. Sadece ihtiyaç duyduğu dış ve iç kaynaklara erişim izni verin.
Secret Yönetimi: Hassas bilgiler (API anahtarları, veritabanı şifreleri) doğrudan runner'ın dosya sistemine kaydedilmemeli, bunun yerine GitHub Secrets, AWS Secrets Manager veya HashiCorp Vault gibi güvenli mekanizmalar aracılığıyla aktarılmalıdır.

Maliyet Optimizasyonu

AWS Spot Instances veya Azure Spot VMs gibi bulut sağlayıcılarının sunduğu daha uygun fiyatlı, ancak kesintiye uğrayabilen kaynakları kullanarak maliyetleri düşürebilirsiniz. Ancak bu, iş akışlarınızın bu tür kesintilere dayanıklı olması gerektiği anlamına gelir.

Sonuç

GitHub Actions self-hosted runner'lar, standart CI/CD limitasyonlarının ötesine geçmek isteyen ekipler için vazgeçilmez bir araçtır. Özelleştirilmiş donanım gereksinimlerinden iç ağ kaynaklarına güvenli erişime, maliyet optimizasyonundan otomatik ölçeklemeye kadar geniş bir yelpazede çözüm sunarlar. Doğru yapılandırma ve güvenlik pratikleriyle, self-hosted runner'lar geliştirme süreçlerinizi daha esnek, güvenli ve verimli hale getirebilir.

← Blog Listesine Dön