Chuyển tới nội dung chính

Tự động comment PR GitHub bằng Webhooks

Hướng dẫn này hướng dẫn bạn kết nối Hermes Agent với GitHub để tự động lấy diff PR, phân tích code changes, và đăng comment — kích hoạt bằng webhook event không cần prompt thủ công.

Khi PR được mở hoặc cập nhật, GitHub gửi webhook POST tới instance Hermes. Hermes chạy agent với prompt hướng dẫn lấy diff qua gh CLI, và response được đăng lại vào PR thread.

Muốn thiết lập đơn giản hơn?

Nếu không có public URL, xem Xây dựng GitHub PR Review Agent — dùng cron jobs poll PR theo lịch, hoạt động sau NAT và firewall.

Tài liệu tham khảo

Xem tham khảo đầy đủ nền tảng webhook tại Webhooks.

Rủi ro prompt injection

Webhook payloads chứa dữ liệu do attacker kiểm soát — PR titles, commit messages, và descriptions có thể chứa chỉ thị độc hại. Khi webhook endpoint public, chạy gateway trong môi trường sandbox (Docker, SSH backend). Xem phần bảo mật bên dưới.

Yêu cầu trước​

  • Hermes Agent đã cài và đang chạy (hermes gateway)
  • gh CLI đã cài và xác thực trên gateway host (gh auth login)
  • URL công khai cho instance Hermes (xem Test local với ngrok nếu chạy locally)
  • Quyền Admin trên GitHub repository

Bước 1 — Bật nền tảng webhook​

Thêm vào ~/.hermes/config.yaml:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      rate_limit: 30

      routes:
        github-pr-review:
          secret: "your-webhook-secret-here"
          events:
            - pull_request

          prompt: |
            A pull request event was received (action: {action}).

            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            Branch: {pull_request.head.ref} → {pull_request.base.ref}
            Description: {pull_request.body}
            URL: {pull_request.html_url}

            If the action is "closed" or "labeled", stop here and do not post a comment.

            Otherwise:
            1. Run: gh pr diff {number} --repo {repository.full_name}
            2. Review the code changes for correctness, security issues, and clarity.
            3. Write a concise, actionable review comment and post it.

          deliver: github_comment
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

Các trường quan trọng:

TrườngMô tả
secretHMAC secret cho route. Fallback về extra.secret global nếu bỏ qua.
eventsDanh sách giá trị X-GitHub-Event header. Rỗng = chấp nhận tất cả.
promptTemplate; {field} và {nested.field} phân giải từ GitHub payload.
delivergithub_comment đăng qua gh pr comment. log ghi vào gateway log.
Payload không chứa code

GitHub webhook payload bao gồm metadata PR nhưng không có diff. Prompt hướng dẫn agent chạy gh pr diff để lấy changes.

Bước 2 — Khởi động gateway​

hermes gateway

Kiểm tra:

curl http://localhost:8644/health
# {"status": "ok", "platform": "webhook"}

Bước 3 — Đăng ký webhook trên GitHub​

  1. Repository → Settings → Webhooks → Add webhook
  2. Điền:
    • Payload URL: https://your-public-url.example.com/webhooks/github-pr-review
    • Content type: application/json
    • Secret: cùng giá trị trong route config
    • Which events? → Select individual events → check Pull requests
  3. Click Add webhook

Bước 4 — Mở test PR​

Tạo branch, push change, mở PR. Trong 30–90 giây, Hermes sẽ đăng review comment.

tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"

Test local với ngrok​

ngrok http 8644

Copy URL https://...ngrok-free.app làm GitHub Payload URL.

Dùng deliver: log khi test locally

Đổi deliver: github_comment thành deliver: log khi test. Chuyển lại sau khi hài lòng với output.

Dùng skill cho review nhất quán​

Thêm skills vào route:

routes:
  github-pr-review:
    secret: "your-webhook-secret-here"
    events: [pull_request]
    prompt: |
      ...
    skills:
      - review
    deliver: github_comment

Lưu ý: Chỉ skill đầu tiên tìm thấy được tải. Hermes không stack nhiều skills.

Gửi response tới Slack hoặc Discord​

# Slack
deliver: slack
deliver_extra:
  chat_id: "C0123456789"

# Discord
deliver: discord
deliver_extra:
  chat_id: "987654321012345678"

Giá trị deliver hợp lệ: log · github_comment · telegram · discord · slack · signal · sms

Hỗ trợ GitLab​

Adapter tương tự hoạt động với GitLab. GitLab dùng X-Gitlab-Token (string match, không HMAC) — Hermes xử lý cả hai tự động.

events:
  - Merge Request Hook

Ghi chú bảo mật​

  • Không bao giờ dùng INSECURE_NO_AUTH trong production
  • Xoay webhook secret định kỳ
  • Rate limiting 30 req/phút per route mặc định
  • Duplicate deliveries được deduplicate qua cache 1 giờ
  • Prompt injection: PR titles, descriptions là attacker-controlled. Chạy gateway trong sandbox.

Xử lý sự cố​

Triệu chứngKiểm tra
401 Invalid signatureSecret trong config.yaml không khớp GitHub webhook secret
404 Unknown routeRoute name trong URL không khớp key trong routes:
429 Rate limit exceededVượt 30 req/phút
Không có commentgh chưa cài hoặc chưa xác thực
Agent chạy nhưng chỉ review mô tả PRPrompt không có lệnh gh pr diff

Tiếp theo​