Claude Code GitHub Actions: kurulum ve iş akışları

Claude Code GitHub Actions, Claude Code’u bir GitHub iş akışı içinde çalıştırmanı sağlar. Bir issue ya da pull request’te @claude diye seslenirsin; Claude kodu okur, yanıt verir, yeni bir dalda düzeltme yazar ya da diff’i inceler, hepsi bir GitHub runner’ında. En hızlı kurulum, Claude Code’u deponda açıp /install-github-app çalıştırmak. Bu komut Claude GitHub App’i kurar, anahtarını bir depo secret’ı olarak saklar ve iş akışı dosyalarını içeren bir pull request açar.

Bu rehber iki kurulum yolunu, resmi anthropics/claude-code-action girdilerini, iki modu (anmalar ve otomasyon), hazır bir PR inceleme iş akışını, secret’ları, maliyet ve izin kontrollerini ve Claude’u yerelde çalıştırmanın daha iyi olduğu durumları anlatıyor. Buradaki her şey Ekim 2026 itibarıyla Anthropic’in belgelerine ve action’ın README dosyasına dayanıyor. Asıl istediğin kırmızı CI build’lerini kendi başına düzelten bir ajansa, onun ayrı bir yazısı var: CI hatasını yapay zeka düzeltsin.

Action ne yapar?

anthropics/claude-code-action@v1, Claude Code ajanını kendi GitHub runner’ında çalıştıran bir GitHub Action. İki modda çalışır:

• Etkileşimli (anmalar). Ona bir prompt vermezsen bir tetikleyici ifade bekler, varsayılanı @claude. İfade bir issue ya da PR yorumunda, bir PR incelemesinde veya yeni bir issue’nun başlığında ya da gövdesinde olabilir. Claude bir yorumla yanıt verir ve değişikliklerle bir dal push edebilir.
• Otomasyon. prompt ayarlarsan Claude, iş akışı tetiklenir tetiklenmez o görevi çalıştırır; anmaya gerek kalmaz. Prompt ya da bir eklenti Claude’a bir yere yazmasını söylemedikçe sonuçlar çalıştırma günlüğüne gider. PR incelemeleri, zamanlanmış raporlar ve issue ayıklama bu şekilde kurulur.

Ajan terminalindekiyle aynı kurallara uyar. CLAUDE.md dosyasını okur, izin verdiğin araçları kullanır ve belirlediğin tur sınırında durur.

1. Adım: /install-github-app ile hızlı kurulum

Claude Code’u depoda aç ve şunu çalıştır:

/install-github-app

Başlamadan önce üç şeyi kontrol et:

• Depo yöneticisisin. Uygulamayı kurmak da secret eklemek de yönetici yetkisi ister.
• Depo github.com üzerinde. Remote gitlab.com ya da bitbucket.org üzerindeyse komut bir uyarı gösterip çıkar.
• GitHub CLI’da giriş yapılmış. Yapmadıysan önce gh auth login çalıştır.

Komut seni adım adım yönlendirir. Claude GitHub App’i depoya kurar ve Claude’un nasıl kimlik doğrulayacağını sorar. Ardından ANTHROPIC_API_KEY (bir API anahtarı) ya da CLAUDE_CODE_OAUTH_TOKEN (Claude aboneliğine bağlı bir token) değerini depo secret’ı olarak kaydeder. Zaten bir anahtar varsa onu yeniden kullanabilir. Son olarak iş akışı dosyalarını içeren bir dal push eder ve birleştirmen için bir pull request açar.

İki iş akışı elde edersin: claude.yml @claude anmalarına yanıt verir, claude-code-review.yml ise pull request’leri inceler. Yarıda durdurmak için Esc’ye bas; iş akışlarını kendin yazmak istiyorsan uygulama kurulduktan sonra “Skip for now” seçeneğini seç. Komutu daha sonra yeniden çalıştırırsan iş akışı dosyasını en son sürüme güncellemeyi önerir.

Hızlı kurulum Claude API ile ve Claude abonelikleriyle çalışır. Amazon Bedrock, Google Cloud ya da Microsoft Foundry kullanıyorsan elle kurulum yolunu ve belgelerdeki bulut sağlayıcı bölümünü izle.

2. Adım: elle kurulum

Komut senin durumuna uymuyorsa aynı üç adımı elle şöyle yaparsın:

1. Claude GitHub App’i kur: github.com/apps/claude adresinden depoya kur. Action; Contents, Issues ve Pull requests izinlerini, her birini okuma ve yazma erişimiyle kullanır.
2. Bir secret ekle: Settings → Secrets and variables → Actions altında:
   • ANTHROPIC_API_KEY: Claude Console’dan alınan, token başına faturalanan bir API anahtarı, ya da
   • CLAUDE_CODE_OAUTH_TOKEN: oluşturmak için yerelde claude setup-token çalıştır; Pro, Max, Team ve Enterprise planlarıyla çalışır.
3. Örnek iş akışını kopyala: action’ın examples/ klasöründeki claude.yml dosyasını .github/workflows/ içine kopyala.

Çalışan bir anma iş akışı:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

İki izin kolayca gözden kaçar. id-token: write, varsayılan GitHub App kimlik doğrulaması için gerekli. actions: read ise Claude’un CI sonuçlarını okumasını sağlar; böylece bir kontrolün neden başarısız olduğunu ona sorabilirsin. Abonelik token’ı kullanıyorsan son satırı claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} ile değiştir.

Bir organizasyon için belgeler, uygulamayı organizasyon düzeyinde kurmayı, anahtarı bir organizasyon Actions secret’ına koymayı ve her depodan yeniden kullanılabilir bir iş akışını çağırmayı öneriyor. Paylaşılan secret’lar için OAuth token yerine API anahtarını da öneriyorlar, çünkü bir token tek bir kişinin aboneliğine aittir. Uzun ömürlü bir anahtarı hiç saklamak istemiyorsan action, anthropic_federation_rule_id ve anthropic_organization_id girdileri üzerinden workload identity federation’ı (OIDC) destekliyor.

3. Adım: issue ve pull request’lerde @claude kullan

İş akışı varsayılan dala girdikten sonra bir yorum yaz:

@claude why does the checkout test fail on Node 22? Fix it if the cause is in our code.

@claude implement this issue. Keep the public API unchanged and add tests.

@claude review the error handling in src/payments/ and suggest changes inline.

Claude bir yorumla yanıt verir. Kodu değiştirdiğinde claude/ ile başlayan bir dala push eder (bunu branch_prefix girdisi değiştirir) ve pull request’i açman için sana bir bağlantı verir. Bir çalıştırmayı kimin başlatabileceğini birkaç kural belirler:

• Yorum yazan kişinin yazma yetkisi olmalı. Yetkisi olmayan kullanıcılar, onları allowed_non_write_users içinde listelemedikçe yok sayılır; bu da kendi github_token değerini ister.
• Botlar yok sayılır, allowed_bots içinde adlarını vermedikçe. Bunu "*" yapmak her botu kabul eder; README bunu herkese açık depolarda yapmamanı söylüyor.
• Tetikleyici tam bir kelime. @claude çalışır, /claude ve @claude-bot çalışmaz. Gerekirse trigger_phrase ile değiştir.

Ayrıca assignee_trigger (bir issue belirli bir kullanıcıya atandığında başlar) ve label_trigger (bir etiket eklendiğinde başlar, varsayılanı claude) da var. Bunları on: içinde doğru issues olay türleriyle eşleştir.

4. Adım: otomatik bir PR inceleme iş akışı

Aşağıdaki inceleme iş akışı, belgelerle birlikte gelen iş akışının ta kendisi. Kimse @claude yazmadan; açılan, güncellenen, yeniden açılan ya da incelemeye hazır hale gelen her pull request’te çalışır:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Her parçanın görevi:

• plugin_marketplaces ve plugins, resmi code-review eklentisini yükler.
• prompt, eklentinin komutunu mevcut PR üzerinde çalıştırır. --comment bulguları satır içi yorumlar olarak ya da tek bir özet yorum olarak yazar.
• claude_args satırı zorunlu. Satır içi yorum aracı için --allowedTools olmadan yorumları yazan MCP sunucusu başlamaz.

Eklenti taslak, kapalı ve önemsiz PR’ları, ayrıca daha önce yorum yaptığı PR’ları atlar. Herkese açık bir deponun fork’larından gelen pull request’ler depo secret’larını alamaz, bu yüzden inceleme onlarda çalışmaz. Anthropic ayrıca hiçbir iş akışı dosyası olmadan PR’ları inceleyen, Code Review adlı ayrı bir yönetilen ürün de sunuyor. Action ise kontrolü sende olan ve kendi runner’ında çalıştırdığın seçenek.

Yapay zeka incelemesinin neyi yakalayıp neyi kaçırdığına daha geniş bir bakış için yapay zeka kod incelemesi yazısına bak.

5. Adım: zamanlanmış ve özel otomasyonlar

prompt ile herhangi bir GitHub olayında herhangi bir görevi çalıştırabilirsin. Günlük bir özet şöyle görünür:

name: Daily report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Summarize yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Unutma: düz bir prompt ile Claude’un, --allowedTools ya da settings girdisindeki bir permissions.allow kuralıyla araç verene kadar ne kabuk erişimi ne de GitHub API erişimi olur. Zamanlanmış iş akışları yalnızca varsayılan daldan çalışır ve GitHub, herkese açık depolarda 60 gün hareketsiz kalan zamanlanmış iş akışlarını devre dışı bırakır.

Gerçekten kullanacağın girdiler

Action’ın çok sayıda girdisi var. Yaygın olanlar şunlar:

README’deki diğer işe yarar girdiler: Claude’un nereye push edeceği için base_branch ve branch_prefix, tek bir güncellenen yorum tutmak için use_sticky_comment, PR ve issue olaylarında takip yorumları yazmak için track_progress, commit’leri imzalamak için use_commit_signing ve additional_permissions (örneğin actions: read). Action ayrıca sonraki adımlar için branch_name, session_id ve structured_output gibi çıktılar döndürür.

Beta sürümünü kullandıysan yükseltme mekanik bir iş. @beta değerini @v1 yap, mode girdisini kaldır, direct_prompt adını prompt olarak değiştir, max_turns ve model değerlerini claude_args içine taşı ve custom_instructions değerini --append-system-prompt haline getir.

Secret’lar: ne nereye gider

• Bir iş akışı dosyasına asla anahtar koyma. ${{ secrets.ANTHROPIC_API_KEY }} ya da ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} kullan.
• Secret’ları işe yarayan en dar düzeyde tut: tek bir depo için depo secret’ı, birçok depo için seçili depolarla sınırlı bir organizasyon secret’ı.
• Herkese açık depolarda show_full_output kapalı kalsın. README, günlüklerdeki tam çıktının secret’ları açığa çıkarabileceği konusunda uyarıyor.
• Issue metnini güvenilmeyen girdi olarak gör. Issue yazabilen herkes, içine gizlediği talimatlarla Claude’u yönlendirmeyi deneyebilir. Asıl savunman yazma yetkisi kuralı; bu yüzden allowed_non_write_users ya da allowed_bots ayarlarını gelişigüzel gevşetme. Prompt enjeksiyonu ve yapay zeka kodlama ajanı güvenliği riskleri daha ayrıntılı ele alıyor.

Maliyeti ve izinleri kontrol altında tutmak

Her çalıştırmanın iki maliyeti var: runner’daki GitHub Actions dakikaları ve Claude token’ları (OAuth token kullanıyorsan abonelik kullanımı). Belgelerin önerdiği kollar:

• Turları sınırla: claude_args: "--max-turns 5" bir çalıştırmanın döngüye girmesini engeller.
• Job’a bir zaman aşımı koy: job üzerinde timeout-minutes kullan.
• Concurrency kullan, böylece art arda gelen push’lar aynı PR için beş inceleme başlatmaz:

concurrency:
  group: claude-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

• Araçları daralt. --allowedTools ile yalnızca görevin ihtiyaç duyduğu komutları ver ve inceleme job’larında, yukarıdaki iş akışındaki gibi, job permissions değerlerini salt okuma tut.
• CLAUDE.md’yi kısa ve somut tut. Claude onu her çalıştırmada yükler, yani uzun bir dosya her seferinde token harcar. CLAUDE.md nasıl yazılır yazısında bir şablon var.
• Somut istekler yaz. “@claude fix the null check in parseDate”, “@claude look at this” demekten daha ucuzdur. Issue şablonları insanların daha iyi istekler yazmasına yardım eder.

Sık yapılan hatalar

• İş akışı varsayılan dalda değil. issue_comment iş akışları yalnızca varsayılan daldan çalışır; önce kurulum PR’ını birleştir.
• Claude’un commit’lerinde CI çalışmıyor. GitHub, varsayılan GITHUB_TOKEN ile yapılan commit’ler için iş akışı başlatmaz. Action’ın Claude GitHub App’i kullanması için github_token: ${{ secrets.GITHUB_TOKEN }} satırını kaldır ya da kendi uygulamandan bir token ver.
• İnceleme hiçbir şey yazmıyor. --allowedTools "mcp__github_inline_comment__create_inline_comment" satırını kontrol et; PR’ın taslak olup olmadığına ya da bir fork’tan gelip gelmediğine bak.
• Claude komut çalıştıramadığını söylüyor. Otomasyon modunda varsayılan olarak hiçbir şeye izin verilmez. Araçları --allowedTools içine ekle.

Ne zaman Claude’u yerelde çalıştırmalı?

Action, sabit bir tetikleyicinin sınırları belli bir işe yol açtığı görevlerde iyi: bir soruyu yanıtlamak, küçük bir issue’yu uygulamak, bir diff’i incelemek, günlük bir özet yazmak. Şu durumlarda pek uygun değil:

• İlerledikçe yön vermek istiyorsun. Ajanı birkaç dakikada bir düzeltmen gerektiğinde bir yorum dizisi yavaş kalır. Yerel bir oturumda araya girer, onaylar ve yönünü değiştirirsin.
• Görev senin ortamına ihtiyaç duyuyor: çalışan bir veritabanı, yerel bir servis, CI’a gitmemesi gereken secret’lar ya da bakman gereken bir arayüz.
• Keşif yapıyorsun. Uzun bir araştırma, kimse izlemezken runner dakikası ve token yakar. Yerelde konudan saptığını görür ve durdurursun.
• Aynı anda birkaç ajan istiyorsun, her biri kendi worktree’sinde, yaklaşımları karşılaştırarak.

Birçok ekip ikisini birden kullanıyor. Action rutin incelemeleri ve küçük issue’ları üstlenir, ağır iş ise birinin izlediği yerelde yapılır.

Yerel tarafı AgentVera ile yapmak

AgentVera; Claude Code, Codex, opencode ve diğer kodlama ajanı CLI’larını kendi kurulumların ve girişlerinle, gerçek terminallerde yan yana çalıştıran bir masaüstü uygulaması. Yukarıdaki ayrımın yerel tarafını karşılar:

• Bölmelerde ve worktree’lerde ajanlar. Birkaç Claude Code ajanını yan yana, her birini kendi git worktree kopyasında çalıştır; diff’leri ve commit’leri Git ve GitHub panelinde gör.
• Push etmeden önce otomatik kod incelemesi: bir ajan turunu bitirdiğinde seçtiğin bir Claude modeli yazdıklarını inceler ve bulguları önem derecesi ve dosya:satır bilgisiyle listeler. Bulguları ajana geri gönderebilir. Bu ücretsiz planda.
• CI/CD merkezi GitHub Actions, GitLab CI ve Jenkins çalıştırmalarını tek yerde listeler. Başarısız bir çalıştırmanın günlükleri tek tıkla yeni bir ajana gider.
• Otomasyonlar (Pro ve Team), CI kırmızıya döndüğünde ya da bir depo üyesi açık bir PR’a yorum yaptığında bir ajan başlatabilir. Ajan kendi worktree’sinde çalışır ve AgentVera asla doğrudan varsayılan dala push etmez.

AgentVera her ajan CLI’ını çalıştırdığı için aynı düzen başka ajanlarla da çalışır. opencode nasıl kullanılır yazısı bu tarafı sağlayıcıdan bağımsız bir ajanla gösteriyor. Denemek için AgentVera’yı indir.

Toparlarsak

Claude Code’u GitHub Actions’a almak için /install-github-app çalıştır, açtığı PR’ı birleştir ve bir issue’ya @claude yaz. Otomatik incelemeler için code-review eklentisi iş akışını --allowedTools satırıyla birlikte ekle. Sonra --max-turns, job zaman aşımları, concurrency, mümkün olan yerde salt okuma izinleri ve iş akışı dosyasına hiç dokunmayan secret’larla işi sınırlı tut. Uzun, keşif odaklı ve ortama bağımlı işleri izleyebileceğin yerel bir oturuma bırak.