Cara Menggunakan Claude Code untuk Alur Kerja CI/CD

Setiap alur deployment (deployment pipeline) mengandung tugas-tugas berulang: memvalidasi changelog, memeriksa perubahan API yang memutus kompatibilitas (breaking API changes), membuat catatan rilis (release notes), dan mengoordinasikan rollback multi-layanan. Claude Code mengubah titik pemeriksaan manual ini menjadi pagar pengaman cerdas otomatis yang berjalan langsung di lingkungan CI/CD Anda. Alih-alih menulis skrip bash yang rapuh, Anda mendapatkan agen penalaran yang memahami basis kode Anda, kontrak API, dan riwayat deployment.

Mengapa Claude Code Harus Ada di Alur CI/CD Anda?

Skrip CI/CD tradisional bersifat deterministik tetapi "bodoh". Mereka menjalankan grep untuk peningkatan versi, git diff untuk deteksi perubahan, dan regex statis untuk validasi API. Ketika tim Anda melakukan refactor monorepo atau memperkenalkan layanan mikro baru, skrip-skrip tersebut akan rusak secara diam-diam. Claude Code menghadirkan pemahaman semantik: ia tahu apa yang merupakan breaking change, dapat menyimpulkan dependensi layanan dari jalur impor, dan menghasilkan rencana deployment kontekstual.

Pola integrasinya lugas: jalankan Claude Code sebagai langkah dalam kontainer di alur Anda, berikan konteks melalui variabel lingkungan, dan biarkan ia mengeksekusi skill yang memvalidasi, menghasilkan, atau mengoordinasikan. Agen ini mengembalikan JSON terstruktur yang dapat ditindaklanjuti oleh langkah-langkah CI berikutnya—menggagalkan build, memicu deployment canary, atau memposting peringatan ke Slack.

💡

Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform All-in-One yang terintegrasi agar Tim Pengembang Anda dapat bekerja sama dengan produktivitas maksimal?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

tombol

Menyiapkan Claude Code di Lingkungan CI/CD

Konfigurasi Kontainer

Jalankan Claude Code dalam kontainer Docker dengan overhead minimal:

# Dockerfile.claude-cicd
FROM node:20-alpine

# Install Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# Set working directory
WORKDIR /workspace

# Copy project files
COPY . .

# Set environment variables for non-interactive mode
ENV ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}"
ENV CLAUDE_CODE_CI_MODE=true
ENV CLAUDE_CODE_QUIET=true

# Default command runs a skill
ENTRYPOINT ["claude"]

Bangun dan uji secara lokal:

docker build -f Dockerfile.claude-cicd -t claude-cicd .
docker run -e ANTHROPIC_API_KEY=sk-ant-... claude-cicd --help

Integrasi GitHub Actions

Buat alur kerja yang dapat digunakan kembali yang memanggil Claude Code untuk tugas validasi tertentu:

# .github/workflows/claude-validation.yml
name: Claude Code Validation

on:
  workflow_call:
    inputs:
      skill_name:
        required: true
        type: string
      parameters:
        required: false
        type: string
        default: '{}'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for change analysis

      - name: Run Claude Code Skill
        uses: docker://claude-cicd:latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          args: |
            --skill "${{ inputs.skill_name }}" \
            --params '${{ inputs.parameters }}' \
            --output /workspace/claude-output.json

      - name: Parse Claude Output
        id: parse
        run: |
          echo "claude_result=$(cat /workspace/claude-output.json)" >> $GITHUB_OUTPUT

      - name: Fail on Breaking Changes
        if: fromJson(steps.parse.outputs.claude_result).hasBreakingChanges
        run: |
          echo "Breaking changes detected: ${{ fromJson(steps.parse.outputs.claude_result).details }}"
          exit 1

Panggil alur kerja ini dari alur CI utama Anda:

# .github/workflows/ci.yml
jobs:
  check-breaking-changes:
    uses: ./.github/workflows/claude-validation.yml
    with:
      skill_name: "api-breaking-change-detector"
      parameters: '{"baseBranch": "main", "changedFiles": "${{ needs.changes.outputs.changed_files }}"}'

Integrasi GitLab CI

Blok script GitLab membuat pemanggilan Claude Code menjadi mudah:

# .gitlab-ci.yml
stages:
  - validate
  - test
  - deploy

claude:validate:api:
  stage: validate
  image: claude-cicd:latest
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  script:
    - claude --skill api-breaking-change-detector 
      --params "{\"baseBranch\": \"$CI_DEFAULT_BRANCH\", \"changedFiles\": \"$CI_COMMIT_CHANGED_FILES\"}"
      --output claude-output.json
    - |
      if jq -e '.hasBreakingChanges' claude-output.json > /dev/null; then
        echo "Breaking API changes detected: $(jq -r '.details' claude-output.json)"
        exit 1
      fi
  artifacts:
    reports:
      dotenv: claude-output.env
    paths:
      - claude-output.json

Bagian artifacts menangkap keluaran Claude untuk pekerjaan-pekerjaan berikutnya, memungkinkan logika deployment kondisional.

Membangun Skill Claude Code Khusus CI/CD

Struktur Skill untuk Tugas Alur

Skill CI/CD membutuhkan tiga komponen:

Deteksi perubahan: Menganalisis git diff, pesan commit, atau diff permintaan gabungan (merge request)
Logika validasi: Menerapkan aturan bisnis (versioning API, cakupan pengujian, pemindaian keamanan)
Generasi tindakan: Menghasilkan perintah alur atau alasan kegagalan

Buat definisi skill:

mkdir -p ~/claude-skills/api-breaking-change-detector
cd ~/claude-skills/api-breaking-change-detector

Definisi SKILL.md

---
name: api-breaking-change-detector
description: Mendeteksi perubahan API yang memutus kompatibilitas dalam spesifikasi OpenAPI dan tipe TypeScript
version: 1.0.0
author: Tim CI/CD
mcp:
  transport: stdio
tools:
  detect-openapi-changes:
    description: Membandingkan dua spesifikasi OpenAPI dan mengidentifikasi perubahan yang memutus kompatibilitas
    parameters:
      baseSpec:
        type: string
        description: Jalur ke file OpenAPI YAML/JSON dasar
        required: true
      headSpec:
        type: string
        description: Jalur ke file OpenAPI YAML/JSON kepala
        required: true
      strictMode:
        type: boolean
        description: Perlakukan perubahan opsional-ke-wajib sebagai perubahan yang memutus kompatibilitas
        default: true
  detect-typescript-changes:
    description: Membandingkan antarmuka TypeScript untuk perubahan yang memutus kompatibilitas
    parameters:
      baseFiles:
        type: array
        items: { type: string }
        description: Pola glob untuk file TypeScript dasar
        required: true
      headFiles:
        type: array
        items: { type: string }
        description: Pola glob untuk file TypeScript kepala
        required: true
---

# Skill Detektor Perubahan API yang Memutus Kompatibilitas

Skill ini menganalisis kontrak API dan definisi tipe untuk mengidentifikasi perubahan yang dapat memutus konsumen.

## Contoh Penggunaan

### Perbandingan OpenAPI
```bash
# Dalam alur CI
claude --skill api-breaking-change-detector 
  --tool detect-openapi-changes 
  --params '{"baseSpec": "openapi/base.yaml", "headSpec": "openapi/head.yaml"}'

Perbandingan TypeScript

claude --skill api-breaking-change-detector 
  --tool detect-typescript-changes 
  --params '{"baseFiles": ["src/types/v1/*.ts"], "headFiles": ["src/types/v2/*.ts"]}'

Format Pengembalian

{
  "hasBreakingChanges": true,
  "details": [
    {
      "type": "field_removed",
      "location": "User.email",
      "severity": "breaking"
    }
  ],
  "recommendations": [
    "Batalkan penghapusan field atau tambahkan marker @deprecated"
  ]
}

Logika Implementasi

Buat index.ts:

import { z } from 'zod';
import { parseOpenAPI } from './openapi-parser';
import { parseTypeScript } from './typescript-parser';
import { diffSchemas } from './diff-engine';

const OpenAPIParams = z.object({
  baseSpec: z.string(),
  headSpec: z.string(),
  strictMode: z.boolean().default(true)
});

const TypeScriptParams = z.object({
  baseFiles: z.array(z.string()),
  headFiles: z.array(z.string())
});

export const tools = {
  'detect-openapi-changes': async (params: unknown) => {
    const { baseSpec, headSpec, strictMode } = OpenAPIParams.parse(params);
    
    const base = await parseOpenAPI(baseSpec);
    const head = await parseOpenAPI(headSpec);
    const changes = diffSchemas(base, head, { strict: strictMode });
    
    return {
      hasBreakingChanges: changes.breaking.length > 0,
      details: changes.breaking,
      recommendations: generateRecommendations(changes)
    };
  },
  
  'detect-typescript-changes': async (params: unknown) => {
    const { baseFiles, headFiles } = TypeScriptParams.parse(params);
    
    const base = await parseTypeScript(baseFiles);
    const head = await parseTypeScript(headFiles);
    const changes = diffSchemas(base, head);
    
    return {
      hasBreakingChanges: changes.breaking.length > 0,
      details: changes.breaking,
      recommendations: generateRecommendations(changes)
    };
  }
};

function generateRecommendations(changes: any) {
  return changes.breaking.map((change: any) => {
    switch (change.type) {
      case 'field_removed':
        return `Field ${change.location} telah dihapus. Tambahkan @deprecated terlebih dahulu, lalu hapus di versi mayor berikutnya.`;
      case 'type_changed':
        return `Tipe ${change.location} berubah. Pertimbangkan untuk menambahkan field baru dengan tipe baru.`;
      default:
        return `Tinjau perubahan: ${JSON.stringify(change)}`;
    }
  });
}

Inti pemikirannya: Claude Code tidak hanya mengembalikan teks; ia mengembalikan data terstruktur yang dapat diurai dan ditindaklanjuti oleh sistem CI.

Alur Kerja CI/CD Praktis dengan Claude Code

Alur Kerja 1: Penjalur Pengujian Cerdas (Intelligent Test Runner)

Alih-alih menjalankan semua pengujian pada setiap commit, jalankan hanya pengujian yang terpengaruh oleh file yang berubah.

# .github/workflows/intelligent-tests.yml
jobs:
  determine-tests:
    runs-on: ubuntu-latest
    outputs:
      test-matrix: ${{ steps.claude.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: claude
        run: |
          CHANGED_FILES=$(git diff --name-only HEAD~1)
          echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
          
          MATRIX=$(claude --skill test-selector \
            --params "{\"changedFiles\": \"$CHANGED_FILES\", \"testPattern\": \"**/*.test.ts\"}" \
            --output - | jq -c '.testMatrix')
          
          echo "matrix=$MATRIX" >> $GITHUB_OUTPUT

  run-tests:
    needs: determine-tests
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJson(needs.determine-tests.outputs.test-matrix) }}
    steps:
      - uses: actions/checkout@v4
      - run: npm test ${{ matrix.testFile }}

Skill test-selector menggunakan analisis statis untuk memetakan impor dan menentukan pengujian mana yang mencakup kode yang berubah.

Alur Kerja 2: Generasi Catatan Rilis Otomatis

Changelog berbasis pesan commit standar sering kehilangan konteks. Claude Code menganalisis deskripsi PR, perubahan kode, dan referensi isu:

# .github/workflows/release.yml
jobs:
  generate-notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Generate Release Notes
        run: |
          claude --skill release-notes-generator \
            --params "{\"fromTag\": \"${{ github.event.inputs.fromTag }}\", \"toTag\": \"${{ github.event.inputs.toTag }}\"}" \
            --output release-notes.md
      
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: release-notes.md
          tag_name: ${{ github.event.inputs.toTag }}

Skill tersebut membaca pesan commit, diff, dan isu yang terhubung untuk menghasilkan catatan rilis naratif dengan panduan migrasi.

Alur Kerja 3: Orkes Pemindaian Keamanan

Jalankan beberapa alat keamanan dan biarkan Claude Code mengkategorikan temuan:

# .gitlab-ci.yml
security-scan:
  stage: validate
  script:
    - trivy image --format json $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA > trivy.json
    - sonar-scanner -Dsonar.analysis.mode=preview > sonar.json
    - claude --skill security-triage \
        --params "{\"trivyReport\": \"trivy.json\", \"sonarReport\": \"sonar.json\"}" \
        --output triage-result.json
    - |
      if jq -e '.criticalIssues > 0' triage-result.json; then
        echo "Critical security issues found"
        exit 1
      fi
  artifacts:
    reports:
      security: triage-result.json

Claude Code mengorelasikan temuan, menghilangkan duplikat, dan memprioritaskan berdasarkan eksploitabilitas, mengurangi "noise" sebesar 80%.

Alur Kerja 4: Koordinasi Deployment Canary

Kooordinasikan rilis canary di beberapa layanan:

// skills/canary-deployment/index.ts
export const tools = {
  'plan-canary': async (params: unknown) => {
    const { services, trafficSplit } = params;
    
    // Query service mesh for current state
    const meshState = await $fetch('http://mesh-api.internal/state');
    
    // Generate deployment sequence
    const plan = services.map(service => ({
      service,
      traffic: meshState[service].traffic * trafficSplit,
      healthChecks: [
        `/health/${service}`,
        `/metrics/${service}/error-rate`
      ],
      rollbackThreshold: 0.05 // 5% error rate triggers rollback
    }));
    
    return { plan, estimatedDuration: `${services.length * 5} minutes` };
  },
  
  'execute-canary': async (params: unknown) => {
    const { plan } = params;
    
    for (const step of plan) {
      await $fetch(`http://mesh-api.internal/traffic/${step.service}`, {
        method: 'POST',
        body: { traffic: step.traffic }
      });
      
      // Wait for health checks
      const healthy = await waitForHealth(step.healthChecks, 30);
      if (!healthy) {
        throw new Error(`Service ${step.service} failed health checks`);
      }
    }
    
    return { success: true, servicesUpdated: plan.length };
  }
};

Alur CI memanggil plan-canary, meninjau rencana, lalu memanggil execute-canary dengan gerbang persetujuan manual.

Penanganan Rahasia dan Izin

Manajemen Rahasia

Jangan pernah memasukkan kunci API secara hardcode dalam kode skill. Gunakan rahasia sistem CI:

# GitHub Actions
- name: Run Claude with Secrets
  run: claude --skill deploy-skill
  env:
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

# Dalam skill
const deployToken = process.env.DEPLOY_TOKEN;
if (!deployToken) throw new Error('DEPLOY_TOKEN not set');

Hak Akses Minimal (Least Privilege)

Jalankan Claude Code dengan izin minimal. Di GitLab:

# .gitlab-ci.yml
claude-job:
  script: ...
  before_script:
    - export ANTHROPIC_API_KEY=${CI_JOB_TOKEN_LIMITED}
  variables:
    GIT_STRATEGY: fetch  # No push access
    CLAUDE_CODE_READONLY: true

Ini mencegah Claude secara tidak sengaja mendorong commit atau menghapus cabang.

Pemantauan dan Observabilitas

Catat Keputusan Claude Code

Tangkap alasan untuk jejak audit:

// Dalam implementasi skill
export const tools = {
  'deploy-service': async (params) => {
    const reasoning = [];
    
    reasoning.push(`Menganalisis commit ${params.commitHash}`);
    const risk = await assessRisk(params.commitHash);
    reasoning.push(`Tingkat risiko: ${risk.level}`);
    
    if (risk.level === 'high') {
      reasoning.push('Deployment diblokir: Risiko tinggi terdeteksi');
      return { approved: false, reasoning };
    }
    
    reasoning.push('Deployment disetujui: Semua pemeriksaan lulus');
    return { approved: true, reasoning };
  }
};

Simpan log di platform observabilitas Anda:

# Log ke Loki/Elasticsearch
- run: |
    claude --skill deploy-service ... | \
    jq -c '{level: "info", message: "Keputusan Claude", data: .}' | \
    promtail --client.url=http://loki:3100/loki/api/v1/push

Metrik yang Perlu Dilacak

Jumlah pemanggilan: Seberapa sering setiap skill berjalan
Tingkat keberhasilan: Persentase eksekusi yang berhasil
Penggunaan token: Biaya per pekerjaan CI
Distribusi keputusan: Berapa banyak build yang diblokir vs disetujui

Penyelesaian Masalah Integrasi CI/CD

Masalah: Claude Code Menggantung

Penyebab: Menunggu prompt interaktif.
Perbaikan: Gunakan flag --quiet dan --non-interactive:

claude --quiet --non-interactive --skill your-skill --params '{}'

Masalah: Server MCP Gagal Memulai dalam Kontainer

Penyebab: Dependensi hilang atau versi Node yang salah.
Perbaikan: Bangun image khusus:

FROM node:20-alpine
WORKDIR /skill
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
CMD ["node", "dist/server.js"]

Masalah: Batas Tingkat (Rate Limiting) oleh Anthropic

Penyebab: Terlalu banyak panggilan API dalam pekerjaan paralel.
Perbaikan: Terapkan antrean permintaan:

import PQueue from 'p-queue';
const queue = new PQueue({ concurrency: 1 });

export const tools = {
  'safe-api-call': async (params) => {
    return queue.add(async () => {
      return await callAnthropicAPI(params);
    });
  }
};

Masalah: Skill Tidak Ditemukan

Penyebab: Jalur relatif dalam konfigurasi MCP.
Perbaikan: Gunakan jalur absolut dan checkout repo skill di CI:

- uses: actions/checkout@v4
  with:
    repository: your-org/claude-skills
    path: .claude-skills

- run: |
    echo "{
      \"mcpServers\": {
        \"api-validator\": {
          \"command\": \"node\",
          \"args\": [\"$PWD/.claude-skills/api-validator/dist/index.js\"]
        }
      }
    }" > ~/.config/claude-code/config.json

Kesimpulan

Claude Code dalam alur CI/CD menggeser otomatisasi dari skrip yang kaku ke agen cerdas yang memahami basis kode, arsitektur, dan aturan bisnis Anda. Dengan mengkontainerkan Claude, mendefinisikan skill khusus, dan berintegrasi dengan GitHub Actions atau GitLab CI, Anda menciptakan alur yang beradaptasi dengan refactoring, menangkap perubahan yang memutus kompatibilitas yang halus, dan menghasilkan wawasan yang dapat ditindaklanjuti. Mulailah dengan satu skill—deteksi perubahan API yang memutus kompatibilitas—dan perluas seiring tim Anda mempercayai otomatisasi. Investasi awal dalam pengembangan skill akan membuahkan hasil dalam mengurangi waktu peninjauan manual dan lebih sedikit insiden produksi.

Ketika skill Anda berinteraksi dengan API internal, validasikan kontrak-kontrak tersebut dengan Apidog untuk memastikan alur yang digerakkan oleh AI Anda tidak menjadi sumber ketidakstabilan.

tombol