Yapay Zeka Ajanı ile Başarısız Olan CI Nasıl Düzeltilir?

Kısa cevap: Başarısız olan CI süreçlerini bir yapay zekâ ajanıyla düzeltmek için CI hata bildirimini bir webhook'a gönderin; kodlama ajanının bu hatayı çözüp çözemeyeceğini denetlemesini, hatayı temiz bir worktree üzerinde yerel olarak yeniden üretmesini ve çözümü bir dala taslak bir pull request olarak göndermesini sağlayın. Sonrasında bir insan inceleyip birleştirir (merge). Yerel ortamda yeniden üretilemiyorsa push da yapılmaz.

Öğleden sonra saat 4'te kırmızıya dönen bir derleme (build), düzeltmenin kendisinden çok daha pahalıya mal olur. Biri yaptığı işi bırakır, logları açar, 900 satırlık kurulum çıktısını kaydırıp geçer ve nihayetinde bir lint hatası ya da güncelliğini yitirmiş bir snapshot bulur. Düzeltme iki dakika sürer; ancak bağlam değişimi (context switch) yirmi dakikayı bulur.

İşte kodlama ajanlarının gerçek değerini kanıtladığı yer tam da bu aralıktır. Muhtemelen masanızda zaten Claude Code, Codex veya başka bir ajan çalıştırıyorsunuzdur. Eksik olan parça ise bağlantı mekanizmasıdır: hatayı fark eden, bunu doğru bağlamla ajana ileten ve ajanın reponuza sadece tahminlere dayalı kodlar push'lamasını engelleyen bir köprü. Bu rehberde söz konusu bağlantıyı GitHub Actions ve bir Sharkly Automation ile kuruyoruz; aynı yapı HTTP isteği gönderebilen her CI aracıyla da çalışır.

Bir yapay zekâ ajanı CI'da neleri iyi çözer (neleri çözemez)?

Bir ajan, dizüstü bilgisayarda yeniden üretilebilen ve küçük, doğrulanabilir bir düzeltmeye sahip hatalarda en iyi sonucu verir. Altyapıdan, kimlik bilgilerinden veya üçüncü taraf bir servisten kaynaklanan hatalarda ise en kötü performansı sergiler. Otomasyona geçmeden önce sınıflandırın:

Bu tablodan çıkan temel kural şudur: Ajan, yalnızca kendi Computer'ı üzerinde önce kırmızıya, ardından yeşile döndüğünü bizzat gördüğü bir düzeltmeyi sunar. DeepSeek Harness ekibinin X'te paylaştığı bir tasarım makalesi bu modeli “sessizce yeniden üret ve düzelt” (silently reproduce and fix) olarak adlandırıyor: bir tetikleyici olayları izler, varsayılan olarak sessiz kalır ve yalnızca doğrulanmış basit bir düzeltmeyi ortaya çıkarır. Bu makale yayına alınmış bir ürünü değil prototip bir tasarımı anlatıyor; ancak ilke, kendi kuracağınız her yapı için geçerlidir.

CI düzeltme döngüsü nasıl çalışır?

Döngü beş bölümden oluşur: bir hata olayı, imzalı bir webhook, düşük maliyetli bir filtre, yalıtılmış bir ortamda yeniden üretim ve bir insan incelemesi denetimi.

1. CI süreciniz başarısızlıkla sonuçlanır.
2. Küçük bir iş akışı (workflow), imzalı bir JSON gövdesini bir webhook URL'sine gönderir (POST).
3. Ajan gövdeyi okur ve yanlış repo veya bir sürüm dalındaki (release branch) hata gibi kapsam dışı her şeyi eler.
4. Ajan bir görev (task) açar, temiz bir worktree'ye checkout yapar, hatayı yeniden üretir ve düzeltir.
5. Bir dala push yapar ve taslak bir pull request açar. Bir insan bunu birleştirir veya kapatır.

3. ve 4. adımlar bir Sharkly Automation olarak çalışır. Automation; zamanlama, görev durumu değişikliği, yorum ifadesi veya webhook gibi bir tetikleyiciyle başlatılan, kaydedilmiş yönergeler ile bunları çalıştıran Agent veya Crew bileşimidir.

1. Adım: CI hatasını bir webhook'a gönderin

GitHub Actions, başka bir iş akışı tamamlandığında tetiklenen bir workflow_run olayına sahiptir. Her türlü tamamlanma durumunda tetiklendiği için bir iş koşuluyla (job condition) failure durumunu filtrelersiniz. GitHub belgelerindeki önemli bir ayrıntı: İş akışı dosyasının varsayılan dalda (default branch) bulunması gerekir, aksi takdirde asla tetiklenmez.

Bu iş akışı, CI adlı bir iş akışını dinler, küçük bir JSON gövdesi oluşturur, bunu imzalar ve gönderir:

name: Report CI failure
on:
  workflow_run:
    workflows: [CI]
    types: [completed]

jobs:
  notify:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - name: Send signed webhook
        env:
          WEBHOOK_URL: ${{ secrets.SHARKLY_WEBHOOK_URL }}
          SIGNING_SECRET: ${{ secrets.SHARKLY_SIGNING_SECRET }}
          REPO: ${{ github.repository }}
          RUN_ID: ${{ github.event.workflow_run.id }}
          RUN_URL: ${{ github.event.workflow_run.html_url }}
          BRANCH: ${{ github.event.workflow_run.head_branch }}
          SHA: ${{ github.event.workflow_run.head_sha }}
        run: |
          BODY=$(jq -nc --arg repo "$REPO" --arg run_id "$RUN_ID" \
            --arg url "$RUN_URL" --arg branch "$BRANCH" --arg sha "$SHA" \
            '{event:"ci_failure",repo:$repo,run_id:$run_id,run_url:$url,branch:$branch,sha:$sha}')
          TS=$(date +%s)
          SIG=$(printf '%s\n%s' "$TS" "$BODY" \
            | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -binary | base64)
          curl -fsS -X POST "$WEBHOOK_URL" \
            -H "Content-Type: application/json" \
            -H "X-Webhook-Timestamp: $TS" \
            -H "X-Webhook-Signature: v1=$SIG" \
            --data-raw "$BODY"

Dal isimleri katkıda bulunanlardan geldiği için iş akışı bunları doğrudan kabuk betiğine (shell script) yapıştırmak yerine env ve jq üzerinden geçirir. Her iki değeri de asla dosyanın içinde tutmayın; şifrelenmiş depo gizli bilgileri (encrypted repository secrets) olarak saklayın.

2. Adım: Automation'ı ve webhook tetikleyicisini oluşturun

Space alanınızda bir Automation oluşturun, bunu düzeltmeyi yapacak Ajan'a atayın ve bir Webhook tetikleyicisi ekleyin. Sharkly, tetikleyiciyi oluşturduğunuzda veya yeniden oluşturduğunuzda tam URL'yi yalnızca bir kez gösterir; bu yüzden doğrudan GitHub secret'ına kopyalayın.

Bir imzalama anahtarı (signing secret) etkinleştirin. Bu olmadan URL, taşıyıcı anahtar (bearer secret) gibi çalışır: URL'ye sahip olan herkes bir çalıştırma başlatabilir. Automations belgelerine göre, bu anahtar etkinleştirildiğinde her isteğin; zaman damgası, bir yeni satır ve ham gövde üzerinden whsec_ anahtarıyla hesaplanan bir Base64 HMAC-SHA256 ile birlikte v1= içeren bir X-Webhook-Signature başlığı taşıması gerekir. Sharkly, 300 saniyeden daha fazla sapan zaman damgalarını reddeder ve belirli bir imzayı 10 dakika içinde yalnızca bir kez kabul eder; böylece ele geçirilen bir istek yeniden oynatılamaz.

Geçerli bir isteğin bir çalıştırma başlatabilmesi için tetikleyicinin etkinleştirilmiş ve Automation'ın Active (Etkin) durumda olması gerekir. Öncelikle Run now ile test edin.

3. Adım: Önce filtreleyen, sonra düzelten yönergeler yazın

Bir webhook'tan başlatılan Automation çalıştırması kendi kendine bir görev (task) oluşturmaz. Çalıştırmanın bağlı olduğu bir görev bulunmadığından yönergeleriniz bir görev açmalıdır; bu sayede her hata için bir kayıt, sorular için bir mesaj dizisi ve ekibinizin görebileceği bir durum sağlanır. Çoğu olayın saniyeler içinde sonlanabilmesi için düşük maliyetli kontrolleri en başta tutun:

You receive a CI failure webhook. The trigger payload is JSON with
event, repo, run_id, run_url, branch, sha.

1. Stop with no output unless event == "ci_failure" and repo is
   acme/web. Stop if branch starts with "release/".
2. Search open tasks for run_id. If one exists, stop.
3. File a task titled "CI fix: <repo> run <run_id>" with run_url in
   the body. Do all further work under that task.
4. Read the failed steps: gh run view <run_id> --log-failed
5. If the cause is a secret, permission, runner, or network problem,
   comment the diagnosis on the task and stop. Change nothing.
6. Check out sha in a fresh worktree. Run the failing command and
   confirm it fails the same way. If it does not reproduce, comment
   what you tried and stop. Never push an unreproduced fix.
7. Make the smallest change that fixes it. Do not edit CI config,
   lockfiles, or tests you were not asked to fix. Rerun the command
   and the nearest test suite.
8. Push to branch ci-fix/<TASK-ID> and open a draft PR with
   gh pr create --draft, task ID in the title. Comment the PR link
   on the task and hand it to a human for review.

Burada iki ayrıntı önem taşır. Durum ve yorum tetikleyicileri şu anda tüm organizasyon genelinde eşleşmektedir; belgelerin girdileri yönergelerin içinde doğrulamanızı önermesinin nedeni de budur. Bir webhook kendi URL'si ile sınırlıdır, ancak 1. adım yine de yanlış yönlendirilmiş isteklere karşı bir önlemdir. Dal adındaki görev kimliği (task ID) ise somut bir işlev görür: GitHub entegrasyonu bağlıyken dalda, PR başlığında veya PR gövdesinde yer alan bir görev kimliği, pull request'i ilgili göreve bağlar.

4. Adım: Bir Computer üzerinde, yalıtılmış bir worktree'de çalıştırın

Computer; Ajanınızın kendi Runtime'ları, dosyaları ve Git kimlik bilgileriyle çalıştığı bağlı ana makinedir (host). Ajanın deposunu Temporary (Geçici) moduna ayarlayın; böylece her çalıştırma kendi görev dizinine ve ayrı bir worktree'ye sahip olur. Bu sayede bir dakika arayla gelen iki hata birbirinin dosyalarını ezemez. Sistemin işleyişi hakkında ayrıntılı bilgi için yalıtılmış worktree'lerde paralel ajanlar makalesine ve git worktree belgelerine göz atabilirsiniz.

Git erişimi GitHub App'ten değil, Computer'dan sağlanır. Entegrasyon pull request'leri bağlar ve issue'ları senkronize eder; klonlama ve push işlemleri ise söz konusu makinedeki SSH anahtarını, HTTPS belirtecini (token) veya gh oturumunu kullanmaya devam eder. Bu kimlik bilgisine yalnızca dallara push yapma yetkisi verin ve bir birleştirmenin inceleme gerektirmesi için varsayılan dalınızı koruma altına alın.

Maliyet ve güvenlik sınırları

Her çalıştırma, Runtime'ın kendi planı üzerinden faturalandırılır. Sharkly token satmaz; bu nedenle bir CI düzeltme çalıştırması, o uzunluktaki bir Claude Code veya Codex oturumu bugün size ne kadara mal oluyorsa tam olarak o kadara mal olur. 1. adımdaki hızlı filtreleme mekanizması temel maliyet kontrolünüzdür: 1. adımda durdurulan bir olay, tam bir yeniden üretim yerine yalnızca birkaç yüz token harcar.

Eşzamanlılık (concurrency) ikinci denetim mekanizmasıdır. Her Computer bir eşzamanlı görev sınırına sahiptir ve geçici dizinlerdeki çalıştırmalar varsayılan olarak bu sınırın yarısını kullanır. Kapasite dolduğunda, ek çalıştırmalar tek bir bilgisayara yüklenmek yerine sıraya girer. 30 kırmızı derlemenin yaşandığı kötü bir sabah, bir sistem çökmesine değil düzenli bir kuyruğa dönüşür.

Geriye kalanlar ise bir kez yazacağınız kurallardır:

• Yalnızca taslak PR'lar. Ajan asla birleştirme (merge) yapmaz. İnceleme onayının nerede durması gerektiğiyle ilgili olarak insan denetimindeki (human-in-the-loop) kodlama ajanları başlıklı yazıya göz atın.
• Çalıştırma başına tek bir deneme. İlk düzeltme kendi tekrar çalıştırmasında başarısız olursa ajan yorum yazar ve durur.
• Bir engelleme listesi (deny list): CI yapılandırması, secret'lar, kilit dosyaları (lockfiles), migrasyonlar.
• Yönergeleri değiştirdiğinizde Automation'ı kendi sayfasından duraklatın ve Run now testi yaptıktan sonra sürdürün.

Güvenmeden önce doğrulayın. Planla, gözlemle, doğrula döngüsü burada da geçerlidir: Repo listesini genişletmeden önce bir haftalık çalıştırma geçmişini inceleyin.

Alternatifler

Bir webhook Automation'ı kullanmak yerine her hata için ayrı bir görev de açabilirsiniz. İş akışını sharkly task create komutunu çağıran bir betiğe yönlendirin ve ardından atanan Ajanın bunu devralmasını sağlayın. Bu yöntemle, ajanın yok sayması gerekenler de dâhil olmak üzere her kırmızı derleme için bir görev oluşturulur; dolayısıyla düşük hacimli depolar için uygundur. Hata ve talepleri zaten GitHub üzerinden yöneten ekipler bir GitHub sorununu yapay zekâ ajanına atama yönteminden de başlayabilir.

Tek bir depoyla başlayın

En çok lint ve tip hatası veren depoyu seçin, yukarıdaki iş akışını kurun ve webhook'un tetiklenmesine izin vermeden önce Automation'ı manuel olarak üç kez çalıştırın. Tek bir ajanın ötesine geçip ölçeklendirmeye hazır olduğunuzda, aynı anda 10 yapay zekâ kodlama ajanı nasıl çalıştırılır rehberi geri kalan her şeyi açıklar. Sharkly'yi kullanmaya başlamak ücretsizdir: Bir Computer bağlayın ve mevcut ajanınızın bir sonraki kırmızı derlemeyi üstlenmesini sağlayın.

Sıkça Sorulan Sorular

Bir yapay zekâ ajanı başarısız CI derlemelerini kendi başına düzeltebilir mi?

Yerel ortamda yeniden üretebildiği lint, tip ve snapshot hatalarını düzeltebilir. Ancak kendi başına birleştirme (merge) yapmamalıdır. Çıktıyı taslak bir PR olarak tutun ve bir insanın onaylamasını sağlayın.

GitHub Actions başarısız olduğunda bir yapay zekâ ajanını nasıl tetiklerim?

types: [completed] içeren workflow_run olayına bağlı ve conclusion == 'failure' iş koşuluna sahip bir iş akışı ekleyin. Bu iş, ajanın webhook URL'sine imzalı bir istek gönderir.

Ajanın yanlış bir düzeltmeyi push'lamasını ne engeller?

Yeniden üretim (repro) kuralı. Ajan hatayı yerel ortamda görmeli, bir değişiklik uygulamalı ve aynı komutun başarıyla geçtiğini bizzat görmelidir. Yeniden üretim yoksa göreve yorum yazılır ve hiçbir push yapılmaz.

Sharkly'nin GitHub entegrasyonu pull request açar mı?

Hayır. Pull request'leri görevlere bağlar ve issue'ları senkronize eder. PR'ı, Computer üzerindeki Git ve gh kimlik bilgilerini kullanarak ajan bizzat açar.

Peki kararsız (flaky) testler ne olacak?

Karar vermeden önce ajana başarısız olan testi birkaç kez yeniden çalıştırtın. Bazı çalıştırmalarda geçip bazılarında kalıyorsa, etrafından dolaşacak bir yama yapmak yerine kararsızlığı göreve bildirmelidir.

Bir CI düzeltme çalıştırmasının maliyeti ne kadardır?

Runtime'ınızın o oturum için kullandığı token miktarı kadardır. Sharkly çalıştırmaları Claude Code, Codex veya API planınız üzerinden faturalandırılır.