Tóm tắt nhanh: Để sửa lỗi CI bằng AI agent, hãy gửi sự kiện CI thất bại đến một webhook, để coding agent kiểm tra xem lỗi đó có nằm trong khả năng xử lý hay không, tái hiện lỗi cục bộ trong một worktree sạch, và đẩy bản sửa lỗi lên một nhánh dưới dạng draft pull request. Con người sẽ xem xét và merge. Không tái hiện được cục bộ đồng nghĩa với việc không đẩy mã nguồn.
Một bản build báo đỏ lúc 4 giờ chiều gây tốn kém nhiều hơn bản thân việc sửa lỗi. Ai đó phải gác lại công việc đang làm, mở log, cuộn qua 900 dòng thông tin thiết lập, rồi phát hiện ra một lỗi lint hoặc một snapshot đã lỗi thời. Sửa lỗi chỉ mất hai phút. Nhưng việc chuyển đổi ngữ cảnh làm việc lại ngốn mất hai mươi phút.
Khoảng trống đó chính là nơi coding agent phát huy giá trị. Bạn có thể đã dùng Claude Code, Codex hoặc một agent nào đó ngay trên máy tính của mình. Mảnh ghép còn thiếu ở đây là sự kết nối: một cơ chế nhận diện lỗi, chuyển thông tin lỗi đó kèm đúng ngữ cảnh cho agent, đồng thời ngăn agent đẩy những phỏng đoán bừa bãi vào repository. Hướng dẫn này sẽ xây dựng cầu nối đó bằng GitHub Actions và Sharkly Automation, và mô hình tương tự cũng áp dụng được cho bất kỳ hệ thống CI nào có khả năng gửi HTTP request.
Những lỗi CI mà AI agent xử lý tốt (và những lỗi không thể)
Agent hoạt động hiệu quả nhất với các lỗi có thể tái hiện trên máy tính cá nhân và có bản sửa lỗi nhỏ gọn, dễ kiểm chứng. Ngược lại, nó xử lý kém nhất đối với các lỗi nằm ở tầng hạ tầng, thông tin xác thực (credentials) hoặc dịch vụ của bên thứ ba. Hãy phân loại trước khi tự động hóa:
| Loại lỗi | Mức độ phù hợp của agent | Lý do |
|---|---|---|
| Lỗi lint và format | Rất phù hợp | Có tính xác định, linter xác nhận được bản sửa lỗi |
| Lỗi kiểu dữ liệu (type error) | Rất phù hợp | Trình biên dịch xác nhận được bản sửa lỗi |
| Snapshot bị hỏng sau khi chủ động thay đổi UI | Tốt | Dễ tái hiện, nhưng cần con người xác nhận xem thay đổi đó có đúng chủ ý hay không |
| Flaky test (test chập chờn) | Tương đối | Tái hiện cần chạy nhiều lần; việc sửa chữa thường liên quan đến race condition thực sự |
| Unit test thất bại sau khi đổi logic | Tương đối | Test có thể đúng và code đang sai |
| Runner hết dung lượng đĩa, timeout mạng | Kém | Không có gì để sửa trong repo |
| Secret bị thiếu hoặc hết hạn, lỗi phân quyền | Không nên dùng | Agent tuyệt đối không được can thiệp vào credentials |
Nguyên tắc rút ra từ bảng này là: agent chỉ gửi bản sửa lỗi khi chính nó đã chứng kiến kết quả chuyển từ đỏ sang xanh trên Computer của mình. Một bài viết thiết kế do đội ngũ DeepSeek Harness đăng trên X gọi mô hình này là “silently reproduce and fix” (âm thầm tái hiện và sửa chữa): một trigger theo dõi các sự kiện, mặc định giữ im lặng, và chỉ hiển thị bản sửa lỗi đơn giản đã được xác nhận. Bài viết đó mô tả một thiết kế thử nghiệm chứ chưa phải sản phẩm hoàn chỉnh, nhưng nguyên lý này áp dụng tốt cho bất kỳ hệ thống nào bạn tự xây dựng.
Vòng lặp sửa lỗi CI hoạt động như thế nào
Vòng lặp này gồm năm phần: sự kiện thất bại, webhook có chữ ký bảo mật, bộ lọc chi phí thấp, môi trường tái hiện cô lập, và bước kiểm duyệt của con người.
- CI của bạn kết thúc một lượt chạy với trạng thái thất bại.
- Một workflow nhỏ gửi payload JSON đã ký tới một webhook URL.
- Agent đọc nội dung payload và loại bỏ bất kỳ thứ gì nằm ngoài phạm vi, chẳng hạn như sai repo hoặc lỗi trên một release branch.
- Agent tạo một task, checkout một worktree mới, tái hiện lỗi và tiến hành sửa chữa.
- Nó đẩy lên một nhánh và mở draft pull request. Con người sẽ merge hoặc đóng PR đó.
Bước 3 và 4 chạy dưới dạng một Sharkly Automation. Một Automation là tập hợp các chỉ dẫn được lưu sẵn cùng với Agent hoặc Crew thực thi chúng, được kích hoạt bởi một trigger: lịch trình, sự thay đổi trạng thái của task, cụm từ trong bình luận, hoặc webhook.
Bước 1: Gửi lỗi CI tới một webhook
GitHub Actions có sự kiện workflow_run được kích hoạt khi một workflow khác hoàn thành. Nó kích hoạt với mọi kết quả (conclusion), vì vậy bạn cần lọc theo failure bằng điều kiện trong job. Một điểm cần lưu ý từ tài liệu của GitHub: file workflow phải tồn tại trên nhánh mặc định, nếu không nó sẽ không bao giờ được kích hoạt.
Workflow này lắng nghe một workflow có tên là CI, tạo một JSON body nhỏ, ký bảo mật và gửi đi:
name: Report CI failure
on:
workflow_run:
workflows: [CI]
types: [completed]
jobs:
notify:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
steps:
- name: Send signed webhook
env:
WEBHOOK_URL: ${{ secrets.SHARKLY_WEBHOOK_URL }}
SIGNING_SECRET: ${{ secrets.SHARKLY_SIGNING_SECRET }}
REPO: ${{ github.repository }}
RUN_ID: ${{ github.event.workflow_run.id }}
RUN_URL: ${{ github.event.workflow_run.html_url }}
BRANCH: ${{ github.event.workflow_run.head_branch }}
SHA: ${{ github.event.workflow_run.head_sha }}
run: |
BODY=$(jq -nc --arg repo "$REPO" --arg run_id "$RUN_ID" \
--arg url "$RUN_URL" --arg branch "$BRANCH" --arg sha "$SHA" \
'{event:"ci_failure",repo:$repo,run_id:$run_id,run_url:$url,branch:$branch,sha:$sha}')
TS=$(date +%s)
SIG=$(printf '%s\n%s' "$TS" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -binary | base64)
curl -fsS -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: v1=$SIG" \
--data-raw "$BODY"
Tên nhánh đến từ người đóng góp (contributors), do đó workflow sẽ chuyển chúng qua env và jq thay vì chèn trực tiếp vào shell script. Hãy lưu cả hai giá trị dưới dạng encrypted repository secrets, tuyệt đối không lưu trong file.
Bước 2: Tạo Automation và trigger webhook tương ứng
Trong Space của bạn, hãy tạo một Automation, gán nó cho Agent chịu trách nhiệm sửa lỗi, và thêm một Webhook trigger. Sharkly chỉ hiển thị URL đầy đủ một lần duy nhất khi bạn tạo hoặc tạo lại trigger, vì vậy hãy sao chép thẳng URL đó vào GitHub secret.
Hãy bật signing secret. Nếu không có, URL sẽ hoạt động như một bearer secret: bất kỳ ai nắm giữ URL đều có thể kích hoạt lượt chạy. Khi có signing secret, theo tài liệu Automations, mỗi request phải mang header X-Webhook-Signature với tiền tố v1= kèm theo mã Base64 HMAC-SHA256 của timestamp, một dấu xuống dòng và phần raw body, được ký bằng secret whsec_. Sharkly sẽ từ chối các timestamp chênh lệch quá 300 giây và chỉ chấp nhận một chữ ký cụ thể một lần trong vòng 10 phút, ngăn chặn việc request bị bắt và gửi lại (replay attack).
Trigger phải được kích hoạt và Automation phải ở trạng thái Active trước khi một request hợp lệ có thể bắt đầu một lượt chạy. Hãy thử nghiệm trước với tính năng Run now.
Bước 3: Viết chỉ dẫn lọc trước, sửa sau
Một lượt chạy Automation từ webhook sẽ không tự động tạo task. Lượt chạy này không liên kết với task nào, vì vậy chỉ dẫn của bạn cần phải tạo một task; việc này giúp mỗi lần lỗi đều có bản ghi theo dõi, luồng thảo luận để đặt câu hỏi và trạng thái mà nhóm của bạn có thể quan sát. Hãy đặt các bước kiểm tra chi phí thấp lên trên cùng để phần lớn sự kiện kết thúc chỉ trong vài giây:
You receive a CI failure webhook. The trigger payload is JSON with
event, repo, run_id, run_url, branch, sha.
1. Stop with no output unless event == "ci_failure" and repo is
acme/web. Stop if branch starts with "release/".
2. Search open tasks for run_id. If one exists, stop.
3. File a task titled "CI fix: <repo> run <run_id>" with run_url in
the body. Do all further work under that task.
4. Read the failed steps: gh run view <run_id> --log-failed
5. If the cause is a secret, permission, runner, or network problem,
comment the diagnosis on the task and stop. Change nothing.
6. Check out sha in a fresh worktree. Run the failing command and
confirm it fails the same way. If it does not reproduce, comment
what you tried and stop. Never push an unreproduced fix.
7. Make the smallest change that fixes it. Do not edit CI config,
lockfiles, or tests you were not asked to fix. Rerun the command
and the nearest test suite.
8. Push to branch ci-fix/<TASK-ID> and open a draft PR with
gh pr create --draft, task ID in the title. Comment the PR link
on the task and hand it to a human for review.
Có hai chi tiết quan trọng ở đây. Hiện tại, các trigger dựa trên status và comment áp dụng cho toàn bộ tổ chức, đó là lý do tài liệu khuyên bạn nên xác thực đầu vào ngay trong phần chỉ dẫn; webhook được giới hạn theo URL của nó, nhưng bước 1 vẫn đóng vai trò bảo vệ trước các request gửi nhầm. Và task ID trong tên nhánh mang lại giá trị thiết thực: khi kết nối GitHub integration, task ID xuất hiện trong branch, tiêu đề PR hoặc nội dung PR sẽ tự động liên kết pull request ngược lại với task.
Bước 4: Chạy trên Computer trong một worktree cô lập
Computer là máy chủ được kết nối nơi Agent của bạn chạy, với Runtimes, file và Git credentials riêng. Hãy đặt repository của Agent sang chế độ Temporary để mỗi lượt chạy có thư mục task riêng và một worktree tách biệt. Nhờ vậy, hai lỗi xảy ra cách nhau một phút sẽ không thể ghi đè lên file của nhau. Để hiểu rõ cơ chế hoạt động, hãy tham khảo bài viết về chạy nhiều agent song song trong các worktree cô lập và tài liệu tham khảo git worktree.
Quyền truy cập Git được cấp từ Computer chứ không phải từ GitHub App. Việc tích hợp chỉ liên kết pull request và đồng bộ issue; còn clone và push mã nguồn vẫn sử dụng SSH key, HTTPS token hoặc thông tin đăng nhập gh trên máy chủ đó. Hãy chỉ cấp quyền push lên các nhánh cho credential đó, đồng thời thiết lập bảo vệ nhánh mặc định để mọi thao tác merge đều bắt buộc phải qua review.
Chi phí và các rào chắn bảo vệ
Mỗi lượt chạy được tính phí dựa trên gói dịch vụ của chính Runtime đó. Sharkly không bán token, vì vậy chi phí cho một lượt chạy sửa lỗi CI tương đương với chi phí một phiên Claude Code hoặc Codex cùng độ dài mà bạn đang trả hiện nay. Bộ lọc xử lý nhanh ở bước 1 là chốt kiểm soát chi phí chính của bạn: một sự kiện dừng lại ở bước 1 chỉ tiêu tốn vài trăm token thay vì toàn bộ quá trình tái hiện lỗi.
Kiểm soát đồng thời (concurrency) là chốt chặn thứ hai. Mỗi Computer đều có giới hạn tác vụ đồng thời, và các lượt chạy trong thư mục tạm thời mặc định sử dụng một nửa giới hạn đó. Khi hết công suất, các lượt chạy phát sinh sẽ được xếp vào hàng đợi thay vì dồn dập đổ vào một máy tính. Một buổi sáng tồi tệ với 30 bản build báo đỏ sẽ trở thành một hàng đợi có trật tự thay vì một sự cố sụp đổ hệ thống.
Phần còn lại là những quy tắc bạn chỉ cần thiết lập một lần:
- Chỉ tạo Draft PR. Agent tuyệt đối không tự merge. Xem bài viết về human-in-the-loop coding agents để biết vị trí đặt chốt kiểm duyệt phù hợp.
- Mỗi lượt chạy chỉ thử một lần duy nhất. Nếu bản sửa lỗi đầu tiên không vượt qua lượt chạy kiểm tra lại, agent sẽ bình luận và dừng lại.
- Danh sách chặn (deny list): cấu hình CI, secrets, lockfiles, migrations.
- Tạm dừng Automation trên trang quản lý khi bạn thay đổi chỉ dẫn, và chỉ tiếp tục sau khi đã kiểm tra thử với Run now.
Hãy kiểm chứng trước khi hoàn toàn tin tưởng. Vòng lặp lập kế hoạch, quan sát, kiểm chứng hoàn toàn phù hợp trong trường hợp này: hãy xem lại lịch sử chạy trong một tuần trước khi mở rộng danh sách repo áp dụng.
Giải pháp thay thế
Bạn có thể tạo một task cho mỗi lần thất bại thay vì dùng Automation qua webhook. Hãy trỏ workflow tới một script gọi lệnh sharkly task create, sau đó để Agent được chỉ định tiếp nhận. Bạn sẽ có một task cho mỗi bản build báo đỏ, bao gồm cả những bản build mà agent nên bỏ qua, vì vậy cách này phù hợp với các repo có số lượng bản build ít. Những đội ngũ đang xử lý issue qua GitHub cũng có thể bắt đầu từ bài viết gán GitHub issue cho AI agent.
Bắt đầu với một repo duy nhất
Hãy chọn repo có nhiều lỗi lint và type nhất, thiết lập workflow như hướng dẫn ở trên, và chạy thử Automation thủ công ba lần trước khi cho phép webhook tự động kích hoạt. Khi bạn đã sẵn sàng mở rộng quy mô vượt ra ngoài một agent, bài viết cách chạy 10 AI coding agent cùng lúc sẽ hướng dẫn những bước tiếp theo. Sharkly hoàn toàn miễn phí để bắt đầu: hãy kết nối một Computer và để agent hiện tại của bạn xử lý bản build báo đỏ tiếp theo.
Câu hỏi thường gặp (FAQ)
AI agent có thể tự sửa các bản build CI bị lỗi không?
Nó có thể sửa các lỗi lint, type và snapshot mà nó tái hiện được ở môi trường cục bộ. Nó không nên tự merge. Hãy giữ kết quả đầu ra dưới dạng draft PR và để con người phê duyệt.
Làm cách nào để kích hoạt AI agent khi GitHub Actions bị lỗi?
Thêm một workflow lắng nghe sự kiện workflow_run với types: [completed] cùng điều kiện job là conclusion == 'failure'. Job đó sẽ gửi một request có chữ ký xác thực tới webhook URL của agent.
Điều gì ngăn agent đẩy lên bản sửa lỗi sai?
Đó là quy tắc tái hiện lỗi. Agent phải tự thấy lỗi xảy ra ở môi trường cục bộ, áp dụng thay đổi, và chứng kiến câu lệnh đó vượt qua thành công. Không tái hiện được lỗi đồng nghĩa với việc chỉ để lại bình luận trên task và không push mã nguồn.
Tính năng tích hợp GitHub của Sharkly có tự mở pull request không?
Không. Tính năng này chỉ liên kết pull request với task và đồng bộ issue. Agent sẽ mở PR bằng Git và thông tin xác thực gh có trên Computer của nó.
Còn với các bài test chập chờn (flaky test) thì sao?
Hãy yêu cầu agent chạy lại bài test bị lỗi nhiều lần trước khi đưa ra kết luận. Nếu nó vượt qua trong một số lần chạy và thất bại ở những lần khác, agent nên báo cáo về hiện tượng flake trên task thay vì cố gắng sửa tạm bợ.
Chi phí cho một lượt chạy sửa lỗi CI là bao nhiêu?
Bằng số lượng token mà Runtime của bạn sử dụng cho phiên làm việc đó. Các lượt chạy trên Sharkly được tính phí theo gói Claude Code, Codex hoặc API của bạn.
