Menggunakan WIF dengan GitHub Actions

Setiap eksekusi alur kerja GitHub Actions dapat meminta token identitas yang ditandatangani dari issuer yang di-host GitHub di https://token.actions.githubusercontent.com. Dengan Workload Identity Federation, alur kerja Anda menukar token tersebut dengan token akses Anthropic berumur pendek, sehingga job CI Anda dapat memanggil Claude API tanpa secret ANTHROPIC_API_KEY yang disimpan di repositori Anda.

Klaim sub pada token mengenkode repositori dan konteks pemicu. Untuk push ke sebuah branch, klaim ini memiliki bentuk repo:<owner>/<repo>:ref:refs/heads/<branch>. Eksekusi pull-request menggunakan repo:<owner>/<repo>:pull_request, dan deployment yang dibatasi environment menggunakan repo:<owner>/<repo>:environment:<name>. Aturan federasi Anda mencocokkan terhadap klaim ini (dan klaim lainnya, seperti repository_owner dan ref) untuk menentukan eksekusi alur kerja mana yang diizinkan untuk melakukan autentikasi.

Prasyarat

• Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
• Repositori GitHub tempat Anda dapat mengedit file alur kerja dan memberikan izin id-token: write.
• Izin untuk membuat service account, federation issuer, dan federation rule di Claude Console untuk organisasi Anthropic Anda.
• ID organisasi Anthropic Anda. Anda dapat menemukannya di Claude Console pada Settings → Organization.

Mengonfigurasi alur kerja Anda

GitHub hanya menerbitkan token identitas untuk job yang secara eksplisit memintanya. Tambahkan izin id-token: write di tingkat alur kerja atau job:

permissions:
  id-token: write
  contents: read

Di dalam job, runner mengekspos dua variabel lingkungan: ACTIONS_ID_TOKEN_REQUEST_URL dan ACTIONS_ID_TOKEN_REQUEST_TOKEN. Panggil URL permintaan dengan token permintaan sebagai kredensial bearer dan audience pilihan Anda sebagai parameter kueri, lalu tulis JSON Web Token (JWT) yang dikembalikan ke sebuah file:

- name: Fetch GitHub OIDC token
  run: |
    curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.anthropic.com" \
      | jq -r .value > /tmp/gha-jwt

Jika Anda lebih memilih JavaScript, actions/github-script mengekspos kemampuan yang sama melalui core.getIDToken(audience):

- name: Fetch GitHub OIDC token
  uses: actions/github-script@v8
  with:
    script: |
      const fs = require('fs');
      const token = await core.getIDToken('https://api.anthropic.com');
      fs.writeFileSync('/tmp/gha-jwt', token);

Token yang telah didekode membawa klaim yang mendeskripsikan eksekusi alur kerja. Aturan federasi Anda mencocokkan terhadap klaim-klaim ini:

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:your-org/your-repo:ref:refs/heads/main",
  "aud": "https://api.anthropic.com",
  "repository": "your-org/your-repo",
  "repository_owner": "your-org",
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "workflow": "CI",
  "actor": "octocat",
  "event_name": "push"
}

Lihat referensi klaim subjek OIDC GitHub untuk daftar lengkap format sub.

Mengonfigurasi Anthropic

Ikuti panduan penyiapan untuk mendaftarkan federation issuer, membuat service account Anthropic, dan membuat federation rule di Claude Console. Gunakan nilai-nilai khusus GitHub Actions berikut.

Federation issuer: GitHub memublikasikan dokumen OIDC discovery dan JWKS-nya secara publik, jadi gunakan mode discovery. Anthropic menyegarkan kunci secara otomatis ketika GitHub merotasinya.

{
  "name": "github-actions",
  "issuer_url": "https://token.actions.githubusercontent.com",
  "jwks_source": "discovery"
}

Federation rule: Cocokkan hanya eksekusi alur kerja yang ingin Anda percaya. Lihat Membatasi alur kerja mana yang dapat melakukan autentikasi untuk cara membatasi cakupan klaim ini dengan aman.

{
  "name": "gha-main",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "repo:your-org/your-repo:ref:refs/heads/main",
    "audience": "https://api.anthropic.com",
    "claims": {
      "repository_owner": "your-org"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Buat sespesifik mungkin sesuai yang diizinkan oleh workload. Longgarkan subject_prefix menjadi repo:your-org/your-repo:* (dipasangkan dengan batasan claims.ref) hanya jika aturan harus mencocokkan beberapa jenis event dari repositori yang sama, karena segmen akhir dari sub bervariasi antara event ref:..., environment:..., dan pull_request.

Memperoleh dan menggunakan token

Atur variabel lingkungan federasi pada job dan panggil SDK seperti biasa. Anthropic() membaca ANTHROPIC_IDENTITY_TOKEN_FILE, menukar JWT pada permintaan pertama, dan menyegarkan token akses secara otomatis sebelum kedaluwarsa.

import anthropic

# Membaca ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID,
# ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID, dan ANTHROPIC_IDENTITY_TOKEN_FILE
# dari lingkungan job.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Setiap token identitas yang diterbitkan GitHub kedaluwarsa sekitar lima menit setelah diterbitkan. Endpoint permintaan token (ACTIONS_ID_TOKEN_REQUEST_URL) tetap valid selama seluruh job berlangsung, sehingga Anda dapat mengambil token baru kapan saja. SDK menukar token pada penggunaan pertama dan menyimpan token akses Anthropic yang dihasilkan dalam cache. Untuk job yang berjalan lebih lama dari masa berlaku token Anthropic, SDK membaca ulang ANTHROPIC_IDENTITY_TOKEN_FILE pada setiap penyegaran, jadi jalankan kembali langkah pengambilan secara berkala (atau bungkus dalam loop latar belakang) untuk menjaga file tetap terkini. Sebagai alternatif, berikan callback penyedia token ke SDK yang memanggil ACTIONS_ID_TOKEN_REQUEST_URL secara langsung alih-alih menggunakan path file.

Memverifikasi penyiapan

Pertukaran yang berhasil mengembalikan access_token yang diawali dengan sk-ant-oat01- dan nilai expires_in dalam detik. Pada 400 invalid_grant, lihat Memecahkan masalah pertukaran yang gagal; penyebab paling umum dari sisi GitHub Actions adalah format klaim sub yang tidak cocok (segmen akhirnya bervariasi antara event ref:..., environment:..., dan pull_request).

Membatasi alur kerja mana yang dapat melakukan autentikasi

Kunci blok match pada aturan ke cakupan tersempit yang sesuai dengan kasus penggunaan Anda:

• Pin ke satu repositori: Gunakan subject_prefix: "repo:your-org/your-repo:*" sehingga repositori lain di organisasi tidak cocok.
• Pin ke branch yang dilindungi: Tambahkan "ref": "refs/heads/main" (atau branch rilis Anda) di bawah claims sehingga eksekusi pull-request dan feature branch tidak cocok.
• Pin pemilik secara eksplisit: Tambahkan "repository_owner": "your-org" di bawah claims sebagai pemeriksaan pertahanan berlapis terhadap kasus tepi parsing sub.
• Pin ke environment deployment: Untuk job deploy, cocokkan subject_prefix: "repo:your-org/your-repo:environment:production" dan batasi environment tersebut dengan required reviewers di GitHub.

Langkah selanjutnya

• Workload Identity Federation: panduan penyiapan lengkap, variabel lingkungan, dan prioritas kredensial.
• Autentikasi: bagaimana federasi dibandingkan dengan kunci API.