GitLab Runner nasıl kurulur, kaydedilir ve yönetilir?

Runner ne yapar ve GitLab ile nasıl konuşur?

GitLab Runner, .gitlab-ci.yml dosyasındaki işleri (job) alıp gerçekten çalıştıran küçük bir uygulamadır. GitLab sunucusu işleri çalıştırmaz; sıraya koyar. Runner ise düzenli aralıklarla GitLab'a bağlanıp kendisine uygun bir iş olup olmadığını sorar. Bağlantıyı runner başlattığı için runner makinesine dışarıdan gelen bir port açmanız gerekmez, yalnızca runner'ın GitLab adresine çıkış yapabilmesi yeterlidir.

Runner farklı kapsamlarda tanımlanır. Instance runner, GitLab kurulumundaki tüm proje ve gruplar tarafından kullanılabilir. Group runner, bir grubun altındaki bütün projelere hizmet eder. Project runner ise belirli bir projeye ayrılır ve genellikle özel donanım ya da gizli ortam gerektiren işler için seçilir. Resmî belgeler, runner'ın GitLab'ın kurulu olduğu sunucudan ayrı bir makineye kurulmasını ister; yük ve güvenlik açısından bu ayrım önemlidir.

Kurmadan önce karar verin: kapsam ve executor

Kurulum komutlarından önce şu kararları vermeniz gerekir: runner hangi kapsamda olacak ve işleri hangi yöntemle çalıştıracak. Çalıştırma yöntemine executor denir ve işlerin izolasyonunu, hızını ve bakım yükünü belirler.

• Docker: Her iş temiz bir konteyner içinde koşar. Çoğu ekip için en dengeli başlangıçtır; bağımlılıklar iş tanımındaki image ile gelir.
• Kubernetes: Runner bir küme içinde çalışır ve her iş için pod açar. Zaten Kubernetes kullanan ve esnek ölçeklenme isteyen kurumlar için uygundur.
• Docker Autoscaler ve Instance: Bulut sanal makinelerini ihtiyaca göre açıp kapatan, ölçekleme odaklı seçeneklerdir.
• Shell: İşi doğrudan makinenin kabuğunda çalıştırır. Kurulumu kolaydır ama işler birbirinden izole olmaz, bu yüzden dikkatli kullanılmalıdır.

Resmî belgelerde SSH executor bakım modundadır; yeni kurulumlarda başka bir seçenek tercih etmek gerekir. Emin değilseniz Docker executor ile başlayın, ihtiyaç doğarsa daha sonra başka bir runner ekleyin.

Linux sunucuya kurulum

Debian ve Ubuntu tabanlı sistemlerde GitLab'ın paket deposunu eklemek için GitLab'ın yayımladığı depo betiği indirilir ve çalıştırılır; ardından paket normal şekilde kurulur. Depo eklendikten sonra kurulum komutu şudur:

sudo apt install gitlab-runner

Red Hat ailesinde karşılığı:

sudo dnf install gitlab-runner

Belirli bir sürüme sabitlemek gerektiğinde apt tarafında yardımcı imaj paketinin de aynı sürümle kurulması gerekir; yalnızca ana paketi sabitlemek bağımlılık hatası verir. Üretimde sürümü GitLab sunucusunun sürümüyle uyumlu tutmak, kayıt isteği biçimi değiştiğinde yaşanan uyumsuzlukları önler.

Kurulum bitince servis çalışır, ancak henüz hiçbir GitLab örneğine bağlı değildir. Bu bağlantıyı kurmak için runner'ın GitLab tarafında oluşturulması ve kayıt komutunun çalıştırılması gerekir.

Runner'ı GitLab'da oluşturup register ile kaydetme

Güncel akışta önce GitLab arayüzünde runner oluşturulur. Instance, group veya project kapsamını seçtikten sonra runner'ın alacağı işleri belirleyen etiketler (tags) girilir. Etiketsiz işleri de alacaksa Run untagged seçeneği işaretlenir. Oluşturma tamamlanınca GitLab, glrt- ön ekiyle başlayan bir runner kimlik doğrulama jetonu üretir. Bu jetonu bir şifre gibi saklayın; eski kayıt jetonu yöntemi kullanımdan kaldırılmıştır.

Ardından runner makinesinde etkileşimli kayıt başlatılır:

sudo gitlab-runner register

Komut sırasıyla GitLab adresini, jetonu, runner açıklamasını, etiketleri, isteğe bağlı bakım notunu ve executor türünü sorar. Otomasyon için aynı işlem etkileşimsiz de yapılabilir:

sudo gitlab-runner register --non-interactive --url "https://gitlab.example.com/" --token "$RUNNER_TOKEN" --executor "docker" --docker-image alpine:latest --docker-pull-policy "if-not-present" --description "docker-runner"

Kayıt tamamlandığında yapılandırma config.toml dosyasına yazılır. Aynı makinede farklı yapılandırmalı birden çok runner istiyorsanız register komutunu yeniden çalıştırmanız yeterlidir.

Docker ile çalışan runner

Runner'ın kendisini de konteyner olarak çalıştırabilirsiniz. Önemli nokta, yapılandırmanın konteyner dışında kalıcı bir hacimde tutulmasıdır; aksi halde konteyner yeniden oluşturulduğunda kayıt bilgisi kaybolur. Belgelerdeki yerel dizin örneği şöyledir:

docker run -d --name gitlab-runner --restart always -v /srv/gitlab-runner/config:/etc/gitlab-runner -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest

Kayıt için çalışan konteynerin içinde gitlab-runner register komutunu docker exec ile çalıştırabilir ya da kısa ömürlü bir konteynerle aynı yapılandırma hacmini bağlayarak kaydı yapabilirsiniz.

Docker soket dosyasını konteynere bağlamak, runner'a ana makinedeki Docker üzerinde geniş yetki verir. Bu nedenle runner'ı yalnızca güvendiğiniz projeler için kullanın ve paylaşılan ortamlarda ayrı, yalıtılmış bir makine ya da otomatik ölçeklenen bir executor tercih edin.

config.toml ile eşzamanlılık ve davranış ayarı

Runner'ın tüm ayarı config.toml dosyasındadır. Root olarak çalışan servislerde dosya genellikle /etc/gitlab-runner dizinindedir. Dosyada genel ayarlar üstte, her kayıtlı runner için ise bir [[runners]] bölümü bulunur. Örnek bir Docker runner bölümü:

[[runners]] name = "docker-runner" url = "https://gitlab.example.com" executor = "docker" [runners.docker] image = "alpine:latest" pull_policy = "if-not-present"

En çok işe yarayan ayarlar şunlardır: concurrent, tüm runner'lar toplamında aynı anda koşabilecek iş sayısını sınırlar; her [[runners]] bölümündeki limit ise o runner'ın üst sınırını belirler. Genel sınır düşük kalırsa, bölüm sınırını yükseltmeniz bir işe yaramaz. request_concurrency, yoğun runner'larda iş isteklerinin paralel yapılmasını sağlar. check_interval, runner'ın yeni iş için ne sıklıkla sorgu yaptığını belirler.

Çoğu ayar için servisi yeniden başlatmak gerekmez; GitLab Runner dosyadaki değişiklikleri kısa aralıklarla kontrol edip yeniden yükler. Sonuç beklediğiniz gibi değilse önce dosyanın söz dizimini, ardından toplam ve runner bazlı sınırları kontrol edin.

Etiket stratejisi ve sık yapılan hatalar

Etiketler iş ile runner'ı eşleştirir. İş tanımında tags: - docker yazıyorsa yalnızca docker etiketli bir runner o işi alır:

build: stage: build tags: - docker script: - echo "build started"

İyi bir etiket düzeni özellikleri anlatır, makine adlarını değil: docker, gpu, windows, high-memory gibi. İşleri bir makineye bağlamak, o makine bakıma girdiğinde pipeline'ları durdurur.

• İş bekleyip hiç başlamıyorsa: etiketler uyuşmuyordur ya da uygun runner çevrimdışıdır. Runner'ın projede etkin olduğunu ve Run untagged ayarını kontrol edin.
• Runner çevrimiçi görünüp iş almıyorsa: kapsam yanlış olabilir; project runner kilitliyse başka projeye açılamaz.
• Jeton sızıntısı: Jetonu betiklere ve depoya yazmayın, CI/CD değişkeni veya gizli yönetim aracı kullanın.
• Sürüm farkı: GitLab sunucusunu yükseltip runner'ı eski bırakmak kayıt ve iş çekme sorunlarına yol açabilir.
• Her şeyi tek runner'a yüklemek: derleme, güvenlik taraması ve dağıtım işleri farklı kaynak ister; ayrı runner ve etiketlerle ayırmak sıra beklemeyi azaltır.

Bu beceriyi Mindset programlarında nerede çalışırsınız?

Runner kurulumu ve işletimi, CI/CD hatlarının sahibi olan DevOps mühendisleri, platform ekipleri ve yazılım ekibinde bu işi üstlenen kıdemli geliştiriciler için gündelik bir iştir. Mindset kataloğundaki CI/CD Pipeline Tasarımı (GitLab) programı bu alanı doğrudan kapsıyor: modül başlıkları arasında GitLab CI/CD mimarisi ve temelleri, gelişmiş pipeline tasarımı, runner yönetimi ve optimizasyon, test ve kalite kapıları ile deployment ve ortam yönetimi yer alıyor.

Kurumsal ekipler için en somut karşılığı, ortak runner havuzunun nasıl tasarlanacağı, hangi projelerin hangi runner kapsamını kullanacağı ve pipeline sürelerinin nasıl izleneceği konusunda ekip içinde ortak bir dil kurmaktır.