Claude Code di GitLab CI/CD: Job, OIDC, dan MR

Job GitLab pertama saya memasang Claude Code dengan sukses lalu gagal dengan pesan claude: not found. Pemasangannya benar-benar berhasil. Installer meletakkan binary-nya di direktori yang tidak ada di path pada image node alpine, dan satu baris export yang hilang mengubah setup yang berfungsi menjadi lima belas menit membaca log yang menyatakan instalasinya sukses.

Itu mewakili integrasi ini secara umum: konsepnya sederhana dan gesekannya sepenuhnya ada di pipa-pipanya. Tulisan ini membahas apa sebenarnya integrasi ini, job minimalnya, pemicu berbasis mention yang harus Anda bangun sendiri, dua jalur autentikasi tanpa kunci untuk provider enterprise, dan flag yang mencegah job liar memakan biaya lebih besar daripada manfaatnya.

Ini CLI di dalam sebuah job, bukan aplikasi GitLab

Tidak ada aplikasi GitLab yang perlu dipasang dan tidak ada layanan yang perlu diotorisasi. Integrasi ini dibangun di atas CLI Claude Code dan Agent SDK: sebuah job memasang CLI-nya, menjalankannya dengan sebuah prompt dalam mode non-interaktif, lalu membiarkannya mengembalikan hasil lewat merge request. Setiap perubahan mengalir melalui MR, jadi peninjau melihat diff-nya dan approval serta branch protection Anda tetap berlaku.

Dua hal mengikuti dari situ. Pertama, integrasi ini masih beta dan dipelihara GitLab alih-alih Anthropic, dengan dukungan yang dilacak lewat sebuah issue GitLab, bukan lewat Anthropic. Kedua, apa pun yang bisa Anda lakukan dengan CLI-nya bisa Anda lakukan di sini — batasannya adalah yang Anda pasang di job, bukan yang dipaksakan integrasinya.

Job minimal, dan baris yang selalu terlewat

Ini seluruh setup-nya: tambahkan variabel ter-mask untuk API key Anda di pengaturan CI/CD proyek, lalu tambahkan sebuah job. Perhatikan baris export di before-script — itulah selisih antara pipeline yang berfungsi dan pipeline yang membingungkan.

# .gitlab-ci.yml — the smallest job that works.
stages:
  - ai

claude:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    GIT_STRATEGY: fetch
  before_script:
    - apk update
    - apk add --no-cache git curl bash
    - curl -fsSL https://claude.ai/install.sh | bash
    # The installer puts claude in ~/.local/bin, which is NOT on
    # PATH in this image. Miss this line and the job fails with
    # "claude: not found" AFTER a successful install.
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - /bin/gitlab-mcp-server || true
    - >
      claude
      -p "Review this MR and implement the requested changes"
      --permission-mode acceptEdits
      --allowedTools "Bash Read Edit Write mcp__gitlab"
      --max-turns 25
  timeout: 30m

Pemicu mention tidak termasuk di dalamnya

Setiap tulisan tentang integrasi ini memperlihatkan seseorang mengetik at-mention di komentar MR lalu Claude menjawab, dan itu membuatnya tampak seolah penanganan komentar sudah bawaan. Bukan. GitLab mendengarkan pemicu apa pun yang Anda konfigurasi, dan run berbasis mention butuh satu bagian yang Anda sediakan sendiri: webhook proyek untuk event komentar yang mengarah ke sebuah listener, yang memanggil API pemicu pipeline dengan konteks komentar sebagai variabel ketika melihat mention tersebut.

Job itu lalu membaca variabel tersebut — input, konteks, dan event-nya — dan meneruskan input-nya ke CLI sebagai prompt, dengan nilai default kalau job dijalankan lewat jalur lain. Kalau mention di komentar Anda tampak tidak melakukan apa-apa, hampir selalu listener-nya yang belum ada, bukan job-nya. Layak juga memeriksa bahwa komentarnya memakai bentuk tanda at alih-alih garis miring, salah ketik yang mengejutkan seringnya.

Autentikasi tanpa kunci untuk Bedrock dan Agent Platform

Untuk lingkungan enterprise, bagian menariknya adalah kedua provider itu tidak membutuhkan kunci tersimpan. GitLab mencetak token OIDC untuk job dari blok id-tokens lalu mengeksposnya ke script, yang menukarnya dengan kredensial sementara saat runtime. Nilai audience-nya harus cocok dengan yang Anda konfigurasikan di identity provider — biasanya URL instance GitLab Anda.

# Amazon Bedrock via OIDC — no static AWS keys anywhere.
claude-bedrock:
  stage: ai
  image: node:24-alpine3.21
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web"'
  id_tokens:
    GITLAB_OIDC_TOKEN:
      # Must match the audience configured on the IAM OIDC
      # identity provider in AWS — usually your GitLab URL.
      aud: https://gitlab.example.com
  before_script:
    - apk add --no-cache bash curl jq git aws-cli
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
    - export AWS_WEB_IDENTITY_TOKEN_FILE="/tmp/oidc_token"
    - printf "%s" "$GITLAB_OIDC_TOKEN" > "$AWS_WEB_IDENTITY_TOKEN_FILE"
    - >
      aws sts assume-role-with-web-identity
      --role-arn "$AWS_ROLE_TO_ASSUME"
      --role-session-name "gitlab-claude-run"
      --web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE"
      --duration-seconds 3600 > /tmp/aws_creds.json
    - export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
    - export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
    - export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"
  variables:
    AWS_REGION: "us-west-2"
    CLAUDE_CODE_USE_BEDROCK: "1"

Google Cloud Agent Platform mengikuti bentuk yang sama lewat Workload Identity Federation: job menulis token OIDC-nya ke sebuah file, menulis konfigurasi kredensial yang credential source-nya menunjuk file itu, lalu mengeksposnya lewat variabel application default credentials. Tidak ada service account key yang diunduh pada titik mana pun. Kedua jalur ini jelas lebih baik daripada secret berumur panjang di variabel CI, dan keduanya butuh sekitar dua puluh menit untuk disiapkan sekali.

Permission: apa yang sebenarnya boleh dilakukan job itu

Ada dua sistem permission terpisah yang berlaku di sini dan mencampuradukkannya menghasilkan kegagalan paling umum, yaitu job yang berjalan mulus lalu tidak bisa berkomentar atau membuka MR:

• Akses API GitLab berasal dari job token secara default, atau dari project access token dengan scope api yang disimpan sebagai variabel ter-mask kalau job token tidak mencukupi untuk proyek Anda.
• Akses tool milik Claude sendiri berasal dari flag allowed-tools, dan tool MCP GitLab harus disebut di sana atau Claude sama sekali tidak bisa menyentuh GitLab, apa pun token-nya.
• Permission mode menentukan apakah edit file disetujui otomatis. Accept-edits adalah pilihan masuk akal di CI, tempat tidak ada siapa pun yang menjawab prompt.

Apa yang benar-benar dikuasai Claude di dalam pipeline

Kerangka yang berguna: sebuah job CI adalah tempat untuk pekerjaan dengan input jelas dan output yang bisa ditinjau. Apa pun yang butuh pertimbangan soal arah produk sebaiknya tetap di sesi tempat Anda bisa mengemudikannya.

Tiga bentuk yang bekerja baik, dan pemicunya:

Menjaga tagihan tetap proporsional

Job CI yang bisa berputar adalah job CI yang bisa menghabiskan uang, dan ada tiga rem independen yang layak disetel sejak run pertama alih-alih sejak tagihan pertama:

• Flag turns membatasi iterasi bolak-balik, dan itulah yang sungguh membatasi belanja token.
• Timeout level job milik GitLab membatasi waktu jam dinding dan karenanya menit runner, yang ditagih terpisah dari token.
• Batas concurrency membatasi berapa banyak job seperti ini berjalan sekaligus, dan itu paling penting di repository sibuk tempat sepuluh MR bisa memicu sepuluh job.

Integrasi GitLab layak disiapkan kalau hidup Anda memang sudah di merge request, dan setup-nya benar-benar kecil — satu job, satu variabel, dan sebuah listener kalau Anda ingin mention. Yang menentukan apakah ia layak bukan konfigurasi pipeline-nya melainkan CLAUDE.md di sebelahnya: job dengan konvensi yang jelas menghasilkan MR yang Anda merge, dan job tanpa itu menghasilkan MR yang Anda tutup. Benahi file itu dulu sebelum menyetel apa pun di YAML.