Bài 7 — Tích hợp CI/CD: agent chạy tự động trên mỗi Pull Request

Agent chỉ thật sự hữu ích khi chạy tự động đúng thời điểm code thay đổi — tức trong CI, trên mỗi Pull Request. Bài này ta gắn Documentation Agent vào GitHub Actions để nó Detect→Verify→Deliver mà không cần ai nhớ chạy tay.

Chiến lược: hai chế độ

• Check mode (bắt buộc) — phát hiện drift, comment lên PR, fail nếu có Critical.
• Fix mode (tùy chọn) — tự sinh bản cập nhật docs và push commit vào nhánh PR để người review.

Bắt đầu bằng Check mode: an toàn, không tự đổi code người khác.

Workflow GitHub Actions

name: doc-agent
on: pull_request
jobs:
  doc-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # can lich su de git diff
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - name: Run doc drift check
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python -m doc_agent check --base origin/${{ github.base_ref }}

fetch-depth: 0 để lấy đủ lịch sử cho git diff. API key lấy từ secrets, không hard-code.

Các bước tích hợp

• Đóng gói agent thành CLI: python -m doc_agent check|fix.
• Trong check, dùng git diff lấy file đổi (Bài 6), chạy phát hiện drift.
• Kết xuất kết quả và comment lên PR qua GitHub API/gh.
• Đặt exit code: có Critical → exit 1 (fail check); còn lại → exit 0.
• Lưu API key trong repo Secrets, tham chiếu qua ${{ secrets.* }}.
• (Tùy chọn) thêm job fix chạy khi có label doc-fix, tự commit bản cập nhật.

Comment lên PR

body = render_markdown_report(drift)
subprocess.run(["gh", "pr", "comment", pr_number, "--body", body])

Báo cáo nên gồm: file, hàm, loại drift, và gợi ý sửa để người review một click là xong.

Kiểm soát chi phí và độ ổn định

• Chỉ chạy trên file đổi — không quét cả repo mỗi PR.
• Cache kết quả theo hash nội dung hàm: hàm không đổi thì không gọi LLM lại.
• Đặt ngân sách token mỗi lần chạy; vượt thì degrade sang chỉ kiểm deterministic.
• Idempotent comment — cập nhật comment cũ thay vì thêm mới mỗi lần push, tránh spam PR.

Khung tư duy: agent phải là "đồng nghiệp tốt", không phải kẻ gác cổng khó chịu

• Chặn merge chỉ khi Critical (docs sẽ khiến người dùng làm sai).
• Với Major/Minor: gợi ý, đừng ép.
• Luôn kèm gợi ý sửa cụ thể, không chỉ báo lỗi.
• Cho phép bỏ qua có chủ đích bằng nhãn (ví dụ skip-doc-check) khi có lý do chính đáng.

Agent làm phiền quá mức sẽ bị team vô hiệu hóa — đó là thất bại lớn nhất.

Fix mode: tự sinh bản vá docs

Sau khi Check mode ổn định và team tin tưởng, bạn có thể bật Fix mode một cách có kiểm soát. Kích hoạt bằng nhãn doc-fix trên PR thay vì chạy tự động mọi lúc:

  doc-fix:
    if: contains(github.event.pull_request.labels.*.name, 'doc-fix')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python -m doc_agent fix --base origin/${{ github.base_ref }}
      - run: |
          git config user.name doc-agent
          git commit -am "docs: cap nhat theo doc-agent" || echo "khong co thay doi"
          git push

Agent commit bản cập nhật lên chính nhánh PR để người review đọc như một commit bình thường — không bao giờ push thẳng lên nhánh chính.

Kiểm soát chi phí và độ ổn định

• Chỉ chạy trên file đổi — không quét cả repo mỗi PR.
• Cache kết quả theo hash nội dung hàm: hàm không đổi thì không gọi LLM lại.
• Đặt ngân sách token mỗi lần chạy; vượt thì degrade sang chỉ kiểm deterministic.
• Idempotent comment — cập nhật comment cũ thay vì thêm mới mỗi lần push, tránh spam PR.

Cập nhật comment idempotent

Để không làm ngập PR, đánh dấu comment của agent bằng một marker ẩn rồi tìm-và-cập-nhật:

MARKER = "<!-- doc-agent-report -->"
# Tim comment cu chua MARKER; neu co thi edit, khong co thi tao moi.
# gh api ... --method PATCH de sua comment theo id

Mỗi lần push, agent chỉnh đúng comment đó thay vì thêm comment mới — PR luôn hiển thị báo cáo mới nhất, gọn gàng.

Sai lầm thường gặp

• Hard-code API key trong YAML. Lộ key. Luôn dùng Secrets.
• Quên fetch-depth: 0. git diff với base fail vì thiếu lịch sử.
• Fail PR trên mọi drift. Team tắt check ngay. Chỉ Critical mới chặn.
• Tạo comment mới mỗi lần push. PR ngập comment. Dùng comment idempotent.
• Chạy Fix mode tự động push mà không ai duyệt. Có thể ghi đè sai. Fix mode nên có người review, kích hoạt có chủ đích.
• Không giới hạn chi phí. Một PR đổi 200 file có thể đốt token lớn. Đặt ngân sách + cache.

Kết bài: agent giờ tự chạy trên mỗi PR như một reviewer docs. Bài 8 ta bàn vận hành thực tế: đo hiệu quả, xử lý ngoại lệ, và mở rộng.