Sử Dụng Claude Code Cho Quy Trình CI/CD

Mỗi quy trình triển khai (deployment pipeline) đều chứa các tác vụ lặp đi lặp lại: xác thực nhật ký thay đổi (changelogs), kiểm tra các thay đổi API gây lỗi (breaking API changes), tạo ghi chú phát hành (release notes) và điều phối việc khôi phục nhiều dịch vụ (multi-service rollbacks). Claude Code biến các điểm kiểm soát thủ công này thành các hàng rào bảo vệ thông minh, tự động hóa, chạy trực tiếp trong môi trường CI/CD của bạn. Thay vì viết các script bash dễ hỏng, bạn có một tác nhân suy luận (reasoning agent) hiểu được codebase, hợp đồng API và lịch sử triển khai của mình.

Tại sao Claude Code lại phù hợp trong quy trình CI/CD của bạn?

Các script CI/CD truyền thống mang tính xác định nhưng kém thông minh. Chúng chạy grep để kiểm tra tăng phiên bản, git diff để phát hiện thay đổi và regex tĩnh để xác thực API. Khi nhóm của bạn tái cấu trúc một monorepo hoặc giới thiệu một microservice mới, các script đó sẽ lỗi một cách âm thầm. Claude Code mang lại khả năng hiểu ngữ nghĩa: nó biết điều gì tạo thành một thay đổi gây lỗi, có thể suy luận các phụ thuộc dịch vụ từ đường dẫn import và tạo ra các kế hoạch triển khai theo ngữ cảnh.

Mô hình tích hợp rất đơn giản: chạy Claude Code dưới dạng một bước được đóng gói (containerized step) trong pipeline của bạn, cung cấp ngữ cảnh cho nó thông qua các biến môi trường và để nó thực thi các kỹ năng xác thực, tạo hoặc điều phối. Tác nhân này trả về JSON có cấu trúc mà các bước CI tiếp theo có thể hành động—thất bại bản dựng, kích hoạt triển khai canary hoặc đăng cảnh báo lên Slack.

💡

Bạn muốn một công cụ kiểm thử API tuyệt vời giúp tạo ra Tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, tất cả trong một để Đội ngũ Phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn, và thay thế Postman với mức giá phải chăng hơn nhiều!

nút

Thiết lập Claude Code trong môi trường CI/CD

Cấu hình Container

Chạy Claude Code trong một Docker container với chi phí thấp nhất:

# 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"]

Xây dựng và kiểm tra cục bộ:

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

Tích hợp GitHub Actions

Tạo một workflow có thể tái sử dụng để gọi Claude Code cho các tác vụ xác thực cụ thể:

# .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

Gọi workflow này từ pipeline CI chính của bạn:

# .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 }}"}'

Tích hợp GitLab CI

Các khối `script` của GitLab giúp việc gọi Claude Code trở nên đơn giản:

# .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

Phần `artifacts` ghi lại đầu ra của Claude cho các job tiếp theo, cho phép logic triển khai có điều kiện.

Xây dựng một kỹ năng Claude Code chuyên biệt cho CI/CD

Cấu trúc kỹ năng cho các tác vụ Pipeline

Một kỹ năng CI/CD cần ba thành phần:

Phát hiện thay đổi: Phân tích git diff, tin nhắn commit hoặc diff của merge request
Logic xác thực: Áp dụng các quy tắc nghiệp vụ (định phiên bản API, độ bao phủ kiểm thử, quét bảo mật)
Tạo hành động: Tạo các lệnh pipeline hoặc lý do thất bại

Tạo định nghĩa kỹ năng:

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

Định nghĩa SKILL.md

---
name: api-breaking-change-detector
description: Detects breaking API changes in OpenAPI specs and TypeScript types
version: 1.0.0
author: CI/CD Team
mcp:
  transport: stdio
tools:
  detect-openapi-changes:
    description: Compare two OpenAPI specs and identify breaking changes
    parameters:
      baseSpec:
        type: string
        description: Path to base OpenAPI YAML/JSON file
        required: true
      headSpec:
        type: string
        description: Path to head OpenAPI YAML/JSON file
        required: true
      strictMode:
        type: boolean
        description: Treat optional-to-required changes as breaking
        default: true
  detect-typescript-changes:
    description: Compare TypeScript interfaces for breaking changes
    parameters:
      baseFiles:
        type: array
        items: { type: string }
        description: Glob pattern for base TypeScript files
        required: true
      headFiles:
        type: array
        items: { type: string }
        description: Glob pattern for head TypeScript files
        required: true
---

# API Breaking Change Detector Skill

This skill analyzes API contracts and type definitions to identify changes that could break consumers.

## Usage Examples

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

So sánh TypeScript

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

Định dạng trả về

{
  "hasBreakingChanges": true,
  "details": [
    {
      "type": "field_removed",
      "location": "User.email",
      "severity": "breaking"
    }
  ],
  "recommendations": [
    "Revert field removal or add @deprecated marker"
  ]
}

Logic triển khai

Tạo `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} was removed. Add @deprecated first, then remove in next major version.`;
      case 'type_changed':
        return `Type of ${change.location} changed. Consider adding a new field with the new type.`;
      default:
        return `Review change: ${JSON.stringify(change)}`;
    }
  });
}

Điểm mấu chốt: Claude Code không chỉ trả về văn bản; nó trả về dữ liệu có cấu trúc mà các hệ thống CI có thể phân tích và hành động dựa trên đó.

Các quy trình CI/CD thực tế với Claude Code

Workflow 1: Trình chạy kiểm thử thông minh

Thay vì chạy tất cả các bài kiểm thử trên mỗi commit, chỉ chạy các bài kiểm thử bị ảnh hưởng bởi các tệp đã thay đổi.

# .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 }}

Kỹ năng `test-selector` sử dụng phân tích tĩnh để ánh xạ các import và xác định bài kiểm thử nào bao gồm mã đã thay đổi.

Workflow 2: Tự động tạo ghi chú phát hành

Các changelog dựa trên thông điệp commit tiêu chuẩn thường thiếu ngữ cảnh. Claude Code phân tích mô tả PR, các thay đổi mã và các tham chiếu vấn đề:

# .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 }}

Kỹ năng này đọc các thông điệp commit, diffs và các vấn đề được liên kết để tạo ra các ghi chú phát hành tường thuật kèm theo hướng dẫn di chuyển.

Workflow 3: Điều phối quét bảo mật

Chạy nhiều công cụ bảo mật và để Claude Code phân loại các phát hiện:

# .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 tương quan các phát hiện, loại bỏ các trùng lặp và ưu tiên theo khả năng khai thác, giảm nhiễu 80%.

Workflow 4: Điều phối triển khai Canary

Điều phối một bản phát hành canary trên nhiều dịch vụ:

// 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 };
  }
};

Pipeline CI gọi `plan-canary`, xem xét kế hoạch, sau đó gọi `execute-canary` với các cổng phê duyệt thủ công.

Xử lý bí mật và quyền hạn

Quản lý bí mật

Không bao giờ mã hóa cứng các khóa API trong mã kỹ năng. Sử dụng các bí mật của hệ thống CI:

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

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

Nguyên tắc ít đặc quyền nhất

Chạy Claude Code với quyền hạn tối thiểu. Trong 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

Điều này ngăn Claude vô tình đẩy commit hoặc xóa nhánh.

Giám sát và khả năng quan sát

Ghi nhật ký quyết định của Claude Code

Ghi lại lý do để theo dõi kiểm toán:

// In skill implementation
export const tools = {
  'deploy-service': async (params) => {
    const reasoning = [];
    
    reasoning.push(`Analyzing commit ${params.commitHash}`);
    const risk = await assessRisk(params.commitHash);
    reasoning.push(`Risk level: ${risk.level}`);
    
    if (risk.level === 'high') {
      reasoning.push('Deployment blocked: High risk detected');
      return { approved: false, reasoning };
    }
    
    reasoning.push('Deployment approved: All checks passed');
    return { approved: true, reasoning };
  }
};

Lưu trữ nhật ký trong nền tảng quan sát của bạn:

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

Các chỉ số cần theo dõi

Số lượt gọi: Tần suất mỗi kỹ năng chạy
Tỷ lệ thành công: Tỷ lệ phần trăm các lần thực thi thành công
Sử dụng token: Chi phí cho mỗi CI job
Phân bố quyết định: Có bao nhiêu bản dựng bị chặn so với được phê duyệt

Khắc phục sự cố tích hợp CI/CD

Vấn đề: Claude Code bị treo

Nguyên nhân: Đang chờ các lời nhắc tương tác.
Cách khắc phục: Sử dụng các cờ `--quiet` và `--non-interactive`:

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

Vấn đề: Máy chủ MCP không khởi động được trong Container

Nguyên nhân: Thiếu dependencies hoặc sai phiên bản Node.
Cách khắc phục: Xây dựng một image riêng biệt:

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

Vấn đề: Giới hạn tần suất bởi Anthropic

Nguyên nhân: Quá nhiều cuộc gọi API trong các job song song.
Cách khắc phục: Triển khai hàng đợi yêu cầu:

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);
    });
  }
};

Vấn đề: Không tìm thấy kỹ năng

Nguyên nhân: Đường dẫn tương đối trong cấu hình MCP.
Cách khắc phục: Sử dụng đường dẫn tuyệt đối và checkout kho lưu trữ kỹ năng trong 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

Kết luận

Claude Code trong các pipeline CI/CD chuyển đổi tự động hóa từ các script cứng nhắc sang các tác nhân thông minh hiểu codebase, kiến trúc và quy tắc nghiệp vụ của bạn. Bằng cách đóng gói Claude vào container, định nghĩa các kỹ năng chuyên biệt và tích hợp với GitHub Actions hoặc GitLab CI, bạn tạo ra các pipeline thích ứng với việc tái cấu trúc, phát hiện các thay đổi gây lỗi tinh vi và tạo ra thông tin chi tiết có thể hành động. Hãy bắt đầu với một kỹ năng duy nhất—phát hiện thay đổi API gây lỗi—và mở rộng khi nhóm của bạn tin tưởng vào tự động hóa. Khoản đầu tư ban đầu vào việc phát triển kỹ năng sẽ mang lại lợi ích đáng kể trong việc giảm thời gian đánh giá thủ công và ít sự cố sản xuất hơn.

Khi các kỹ năng của bạn tương tác với các API nội bộ, hãy xác thực các hợp đồng đó bằng Apidog để đảm bảo các pipeline do AI điều khiển của bạn không trở thành nguồn gây ra sự không ổn định.

nút