GitHub Actions Runner Güncellemesi: Workflow Neden Durur?

GitHub Actions runner güncellemesi yapılmadığında, sürüm politikasının dışında kalan self-hosted runner yeni iş alamayabilir. Ancak bekleyen veya başarısız bir workflow, tek başına eski sürümü kanıtlamaz. Önce ilgili job’ın hedeflediği etiketleri ve grubu, runner’ın çevrim içi ve boşta olup olmadığını, bağlantısını ve işi kabul edip etmediğini ayrı ayrı kontrol et.

Self-hosted runner güncel değilse workflow neden bekler?

Runner yazılımı varsayılan olarak otomatik güncellenir. Otomatik güncellemeyi kapattıysan yeni runner sürümü yayımlandıktan sonra 30 gün içinde güncelleme yapman gerekir. GitHub’ın politikasına göre bu süre aşıldığında ilgili runner’a iş gönderilmez. Kritik güvenlik güncellemesi gerektiğinde de güncelleme uygulanana kadar iş ataması durdurulur. Dolayısıyla workflow dosyasının doğru olması, runner’ın iş almaya uygun olduğunu tek başına göstermez.

Teşhiste belirtileri ayır: kuyrukta bekleme için runner eşleşmesini ve iş kabulünü, Offline görünme için uygulamanın çalışmasını ve bağlantısını incele. Job başlayıp bir adımda hata verdiyse o adımın loguna yönel. Güncelleme gerektiren bir geçiş uyarısını ise doğrudan bağlantı kopması gibi yorumlama; uyarının sürüm koşulunu ve kapsamını kontrol et.

25 Eylül 2026 tarihinin kapsamı: GitHub’ın resmî takviminde bu tarih, GitHub Enterprise Cloud için sürüm gereksinimlerinin tam uygulanmasının planlanan başlangıcıdır. Aynı takvimde 9 Eylül 2026 için belirtilen Config + Runtime brownout, ilgili sürüm gereksinimlerini karşılamayan runner’larda kayıt ve iş çalıştırmanın geçici olarak engellenmesini kapsar. Veri yerleşimi seçeneği bulunan ortamların takvimi ayrıdır; bu tarihleri tüm kullanıcıları etkileyen genel kesinti duyurusu olarak yorumlama.

Kayıtlı görünmek neden job çalıştırmaya yetmez?

Kayıt, runner’ın bir depoya, kuruluşa veya enterprise hesabına tanıtılmasıdır; uygulamanın çalışmaya devam ettiğini göstermez. Job kabul edebilmesi için yerel runner süreci ya da servis olarak kurduysan ilgili servis çalışmalı ve GitHub’a bağlanmalıdır. Kayıt işleminin başarılı olması ile bir işin fiilen alınması farklı aşamalardır.

Deponun veya kuruluşunun Settings → Actions → Runners ekranında Idle, bağlı ve iş çalıştırmaya hazır; Active, bir iş çalıştırıyor; Offline ise GitHub’a bağlı değil anlamına gelir. Aşağıdaki tablo, resmî durum tanımlarını, yönlendirme kurallarını ve log inceleme yaklaşımını teşhis adımlarına dönüştürür; belirtileri kesin kök neden olarak sunmaz.

Örnek teşhis: Job runs-on: [self-hosted, linux, gpu] istiyor, tek runner’ında ise gpu etiketi bulunmuyorsa runner Idle olsa da eşleşmez. Grup da belirtilmişse grup ve etiket koşulları birlikte sağlanmalıdır. Bu örnekte ilk düzeltme adayı sürüm değil, hedeflemedir; etiketi ancak runner gerçekten gereken donanıma sahipse ekle.

Yerel tarafta Listening for Jobs mesajını işin alındığına dair kanıtla karıştırma: bu mesaj iş beklemeye hazır olmayı gösterir. İlgili denemenin zamanında görülen Running job: kaydı ise işin alınarak başlatıldığını gösterir. Eski bir log satırını güncel çalışma durumunun kanıtı sayma.

Runner sürümü, bağlantı ve loglar nasıl kontrol edilir?

Teşhisi tek bir ekrana bakarak değil, aynı zaman aralığına ait beş kanıtı karşılaştırarak yapın: GitHub arayüzü, yerel runner sürümü, süreç veya servis durumu, bağlantı kontrolü ve test job’ı.

1. Arayüz durumunu kaydedin. Runner’ın kayıtlı olduğu depo ya da organizasyonda Settings > Actions > Runners bölümünü açın. Runner adını, işletim sistemini, etiketlerini, grubunu ve durumunu not edin. Idle bağlı ve iş bekliyor, Active job çalıştırıyor, Offline ise GitHub ile bağlantı kurulamadığını gösterir. Ayrıca workflow içindeki runs-on değerinin bu etiket ve grupla eşleştiğini kontrol edin.
2. Yerel sürümü doğrulayın. Kurulum dizininde runner’ı kontrollü biçimde çalıştırın: Linux ve macOS’ta ./run.sh, Windows’ta run.cmd. Başlangıç çıktısındaki Current runner version satırını ve aynı başlangıca ait Runner_ tanılama kaydını saklayın. Sürümü sabit bir eşikle karşılaştırmak yerine GitHub’ın ilgili işletim sistemi ve mimari için yayımladığı güncel kurulum talimatlarını esas alın.
3. Servis veya süreci inceleyin. Servis kurulmuşsa, kurulum dizininden şu resmî betiklerle durum alın:

Linux:   sudo ./svc.sh status
macOS:   ./svc.sh status
Windows: Get-Service "actions.runner.*"

Servis “çalışıyor” görünse bile GitHub arayüzünde runner Offline ise süreç ile GitHub bağlantısını birlikte inceleyin; yalnızca işletim sistemi servis durumuna güvenmeyin.

1. Bağlantıyı ayrı test edin. Runner kurulumundaki config betiğinin --check seçeneğiyle gerekli GitHub servislerine erişimi denetleyin. Çıktıdaki PASS ve FAIL sonuçlarını, ayrıntıların yazıldığı _diag dosyalarıyla eşleştirin. Token’ı çalışma günlüğüne veya destek kaydına olduğu gibi kopyalamayın.
2. Job kabulünü gözlemleyin. Doğru etiket ve grubu kullanan, tek bir zararsız adımı bulunan geçici bir test workflow’u çalıştırın. Kuyruğa alınma zamanını, GitHub’daki runner durumunu ve yerel loglarda Listening for Jobs, Running job ya da bağlantı hatası satırlarını karşılaştırın. _diag içindeki Runner_ dosyaları uygulama başlangıcını, Worker_ dosyaları ise iş yürütmesini gösterir.

Her adımda runner adı, işletim sistemi, etiketler, durum, hata zamanı ve ilgili log satırlarını aynı notta tutun. Bu akışı algoritmik düşünme alıştırması gibi adımlara bölerek temel altyapınızı gözden geçirmek isterseniz ücretsiz yazılım ve algoritmik düşünme bilgi testlerini kullanabilirsiniz.

Güncelleme öncesi runner nasıl güvenle hazırlanır?

Güncelleme başlamadan önce aktif job’ları ve son başarılı çalışmayı kaydedin, yeni job kabulünü kısa süreliğine durdurabileceğiniz bir bakım penceresi belirleyin. Güncelleme paketini, runner’ın işletim sistemi ve mimarisi için GitHub’ın güncel kurulum ekranında gösterilen adımlara göre seçin; sürüm numarasını sabit bir metinle takip etmeyin.

• Yedek kapsamı: Kurulum dizininin dosya listesini, gizli olmayan yapılandırma dosyalarını ve gerekiyorsa hassas veri taramasından geçirilmiş _diag kayıtlarını saklayın. Servis birimi, macOS launchd ayarı, Windows hizmeti veya kullandığınız görev zamanlayıcısı ayarlarını da belgeleyin. Özel etiketleri, runner grubunu, workflow YAML dosyalarını ve çalışma ortamına ait operasyon notlarını ayrıca kaydedin.
• Gizli veriler: Kimlik bilgilerini, kayıt dosyalarını, token’ları ve secret değerlerini sıradan yedek arşivine gelişigüzel eklemeyin. Yeniden kayıt veya taşıma gerekiyorsa GitHub’ın ilgili prosedürünü izleyin ve yeni, süreli kayıt token’ı kullanın; kayıt token’ları sınırlı süreyle geçerlidir. Yetkileri de ihtiyaç duyulan en düşük seviyede tutun.

Aktif job kalmadığını doğruladıktan sonra servisi işletim sistemine göre durdurun:

Linux:   sudo ./svc.sh stop
macOS:   ./svc.sh stop
Windows: Stop-Service "actions.runner.*"

Güncelleme tamamlandıktan sonra aynı servis betikleriyle başlatın: Linux’ta sudo ./svc.sh start, macOS’ta ./svc.sh start, Windows’ta Start-Service "actions.runner.*". Servis dosyasını elle değiştirmek yerine GitHub’ın servis yönetimi yönergelerini kullanın.

Güncelleme sonrası test workflow'u nasıl doğrulanır?

Güncellemeden sonra en güvenli doğrulama, yalnızca workflow_dispatch ile manuel çalıştırılan küçük bir test job'ı göndermektir. runs-on satırındaki etiketleri kendi runner ayarlarındaki değerlerle değiştir; birden fazla etiket kullanıyorsan runner'ın bu etiketlerin tamamına sahip olması gerekir.

name: Self-hosted runner smoke test

on:
  workflow_dispatch:

jobs:
  runner-smoke-test:
    # runner-test yerine hedef runner'daki benzersiz etiketi yazın.
    runs-on: [self-hosted, runner-test]

    steps:
      - name: Runner bilgileri ve işletim sistemi (Unix)
        if: ${{ runner.os != 'Windows' }}
        shell: bash
        run: |
          printf 'RUNNER_NAME=%s ' "$RUNNER_NAME"
          printf 'RUNNER_OS=%s ' "$RUNNER_OS"
          printf 'RUNNER_ARCH=%s ' "$RUNNER_ARCH"
          printf 'runner.name=%s ' '${{ runner.name }}'
          printf 'runner.os=%s ' '${{ runner.os }}'
          printf 'runner.arch=%s ' '${{ runner.arch }}'
          printf 'runner.environment=%s ' '${{ runner.environment }}'
          uname -a

      - name: Runner bilgileri ve işletim sistemi (Windows)
        if: ${{ runner.os == 'Windows' }}
        shell: pwsh
        run: |
          "RUNNER_NAME=$env:RUNNER_NAME"
          "RUNNER_OS=$env:RUNNER_OS"
          "RUNNER_ARCH=$env:RUNNER_ARCH"
          "runner.name=${{ runner.name }}"
          "runner.os=${{ runner.os }}"
          "runner.arch=${{ runner.arch }}"
          "runner.environment=${{ runner.environment }}"
          Get-CimInstance Win32_OperatingSystem |
            Select-Object Caption, Version, OSArchitecture

Başarılı testte job kuyruğundan çıkar, hedeflenen runner üzerinde başlar ve loglarda runner adı, işletim sistemi, mimari bilgisi ile makinenin işletim sistemi çıktısı görünür. Runner uygulamasının sürümünü workflow dosyasına sabitlemek yerine job başlangıcındaki otomatik logda yer alan Current runner version satırını veya kurulum dizinindeki _diag/Runner_*.log dosyasını kaydet. Yerel resmî doğrulama için runner kurulum dizininde Linux ve macOS'ta ./bin/Runner.Listener --version, Windows'ta .binRunner.Listener.exe --version komutu kullanılabilir.

• Job kuyruğa alınıyorsa: Önce runs-on etiketlerini, runner'ın çevrim içi ve boşta durumunu, kayıt kapsamını ve bağlantısını kontrol et.
• Adımlar başlamadan hata oluşuyorsa: Yerel servis veya sürecin çalıştığını, servis hesabının yetkilerini ve GitHub'a bağlantıyı incele.
• İşletim sistemi komutu başarısızsa: Komutun seçilen shell ve platformla uyumlu olduğunu yeniden kontrol et; Unix komutunu Windows'ta, PowerShell komutunu Unix ortamında çalıştırma.

Manuel çalıştırma düğmesi görünmüyorsa workflow dosyasının varsayılan dalda bulunduğunu da kontrol et. GitHub, manuel tetikleme ve runner yönlendirmesini bu yapılandırma üzerinden değerlendirir.

Tek akışta arıza teşhis kontrol listesi ve yönetilen runner kararı

Aşağıdaki sıra, sorunun sürümden mi, kayıttan mı yoksa bağlantıdan mı kaynaklandığını kanıt toplayarak daraltır:

1. Workflow durumunu kaydet: Run kimliğini, job durumunu ve kuyruğa giriş zamanını not al. Job hiç başlamadıysa yönlendirme adımına geç.
2. Çevrim içi ve boşta durumunu kontrol et: Repository veya kuruluş ayarlarındaki Runners ekranında runner'ın Idle olup olmadığına bak. Offline ise yerel servis ve bağlantıyı incele.
3. Etiket ve kayıt eşleşmesini doğrula: Workflow'daki tüm runs-on etiketlerini runner listesindeki etiketlerle karşılaştır. Eksik etiket veya yanlış kayıt kapsamı varsa job bekler.
4. Yerel süreç ya da servisi incele: Linux'ta servis durumunu, macOS'ta launchd kaydını, Windows'ta Hizmetler ekranını kontrol et. Süreç çalışmıyorsa güncelleme teşhisine geçmeden önce servisi düzelt.
5. Sürüm ve tanılama loglarını kontrol et: Current runner version satırını, Runner_ günlüklerini ve job başladıysa ilgili Worker_ günlüğünü karşılaştır. Güncelleme tamamlanmamışsa resmî güncelleme adımını tekrarla.
6. Bağlantıyı test et: Runner kurulum dizinindeki resmî config kontrolünü kullan. Başarısız sonuçta DNS, proxy, sertifika, güvenlik duvarı ve dış HTTPS erişimini incele; test başarılı olduğu hâlde job bekliyorsa etiket ve durum adımlarına dön.
7. Güvenli yedek al: Workflow dosyasını, runner adı-et בקרeti-grup bilgisini ve gerekli tanılama loglarını güvenli bir konuma kaydet. Token, kimlik bilgisi ve gizli dosyaları depoya veya herkese açık bir klasöre kopyalama.
8. Güncelleme prosedürünü uygula: Runner'ı kullanan servis ve süreç yönetimini dikkate alarak GitHub'ın resmî paket ve güncelleme yönergelerini kullan. İşlem sonrasında runner listesindeki çevrim içi durumunu yeniden kontrol et.
9. Test workflow'u ile doğrula: Manuel test job'ını çalıştır. Job hedef makinede başlıyor ve işletim sistemi çıktısı beklenen sistemle eşleşiyorsa temel runner katmanı çalışıyor demektir; sorun bundan sonra workflow adımlarında aranmalıdır.

Self-hosted yaklaşımı; özel ağa erişim, özel donanım, kurum içi servisler veya özelleştirilmiş araç seti gerçekten gerektiğinde anlamlıdır. Buna karşılık makine bakımı, erişilebilirlik, güncelleme ve güvenlik operasyonunu azaltmak ve standart bir çalışma ortamıyla yetinmek istiyorsan yönetilen, yani GitHub-hosted runner seçeneğini değerlendirebilirsin. Self-hosted makinelerde güvenilmeyen workflow kodunun çalıştırılması kalıcı dosyalara ve yetkilere erişim riski oluşturabileceği için depo görünürlüğü, pull request politikaları ve runner erişim grupları ayrıca ele alınmalıdır.

Yazılım öğrenme sürecini kişiye göre yapılandırmak isteyen okuyucular, Berk Akademi'nin kişiye göre şekillenen online yazılım eğitimi seçeneklerini inceleyebilir.

Bu kontrol sırasını izlediğinde, runner güncellemesini rastgele tekrar etmek yerine her aşamada somut bir kanıtla ilerleyebilir ve arızanın kaynağını daha hızlı daraltabilirsin.