Triage GitHub Issues tự động vào Notion với Qwen & OpenRouter

1. Tổng quan dự án (Overview)

Đây là workflow tự động hóa quy trình phân loại GitHub Issues bằng AI. Khi một issue mới được mở trên repository, workflow phân loại theo loại (bug, feature, question, documentation, other), gán mức ưu tiên (high, medium, low) và tạo tóm tắt một câu — kết quả được ghi vào Notion database và đăng comment trực tiếp trên issue. Không cần dịch vụ triage bên ngoài, không SaaS subscription. Chạy trên chính instance n8n của bạn.

Mục tiêu chính: Loại bỏ 30-60 giây sắp xếp thủ công mỗi issue bằng cách tự động phân loại và đưa vào Notion board — con người vẫn quyết định cuối cùng nhưng không cần phân loại tay.

🚀 Điểm nổi bật: AI chỉ phân loại, không ra quyết định — không tự đóng issue, không tự gán người. Con người review trên Notion board và quyết định hành động. Workflow có cơ chế fallback: nếu LLM gặp sự cố, issue vẫn được ghi vào Notion với giá trị mặc định, không bao giờ bị bỏ sót.

Xem Notion board demo được populate bởi workflow này: Notion Demo Board

---

2. Tính năng nổi bật (Key Features)

A. AI Triage Thông Minh với Prompt Cấu Trúc AI phân loại và ưu tiên issue dựa trên prompt có định nghĩa rõ ràng cho từng category và priority level, đảm bảo kết quả phân loại nhất quán.

• Chi tiết 1: Prompt gửi đến model bao gồm định nghĩa chi tiết cho từng loại issue (bug, feature, question, documentation, other) và từng mức ưu tiên (high, medium, low), giúp model phân loại chính xác và nhất quán.
• Chi tiết 2: Nếu LLM call thất bại, node fallback tự động gán giá trị mặc định (category: other, priority: medium) — issue vẫn được track trong Notion, không bị mất.

B. Kiểm Tra Trùng Lặp & Xử Lý Lỗi Robust Workflow được thiết kế để không bao giờ bỏ sót issue và không tạo bản ghi trùng lặp trong Notion.

• Chi tiết 1: Duplicate check query Notion database theo Issue URL trước khi xử lý — nếu issue đã được triage trước đó, workflow dừng lại, tránh gọi API không cần thiết và tạo bản ghi trùng.
• Chi tiết 2: Nếu chính duplicate check thất bại (Notion API timeout, rate limit, token sai), error branch kích hoạt và workflow vẫn tiếp tục triage — triage dư tốt hơn bỏ sót issue do lỗi tạm thời.

C. Triển Khai Lên Cả Notion & GitHub Kết quả triage không chỉ nằm trong Notion mà còn được đăng trực tiếp trên GitHub issue dưới dạng comment có định dạng.

• Chi tiết 1: Comment trên GitHub hiển thị đầy đủ category, priority, summary và suggested labels. Nếu dùng fallback values do LLM unavailable, comment sẽ cảnh báo để team review thủ công.
• Chi tiết 2: Notion database là single view tập trung — tất cả issue đến đều được phân loại và ưu tiên, team có thể filter, sort, assign mà không cần chuyển tool.

D. Dữ Liệu Riêng Tư & Self-Hosted Dữ liệu issue không bao giờ rời khỏi infrastructure của bạn. LLM call duy nhất đi qua OpenRouter, và có thể thay bằng model tự host để giữ mọi thứ internal.

---

3. Hướng dẫn cài đặt chi tiết (Setup Guide)

Để chạy workflow này, bạn cần chuẩn bị các tài nguyên sau:

⚙️ Yêu cầu môi trường (Prerequisites)

• n8n Instance: Bản self-hosted hoặc cloud đều được.
• GitHub Personal Access Token: Fine-grained, quyền Issues (read/write) và Webhooks (read/write). Scope vào repository muốn theo dõi. Tạo tại: Settings → Developer settings → Fine-grained tokens.
• Notion Account: Có internal integration. Tạo tại notion.so/my-integrations, copy token.
• OpenRouter API Key: Hoặc bất kỳ endpoint tương thích OpenAI nào.

Các bước thực hiện:

1. Cấu hình GitHub: Tạo Fine-grained PAT với quyền Issues read/write và Webhooks read/write. Thêm credential GitHub vào n8n.
2. Tạo Notion Database: Tạo database với các properties:

   1. Title (title)
   2. Issue URL (url)
   3. Author (rich_text)
   4. Category (select: bug, feature, question, documentation, other)
   5. Priority (select: high, medium, low)
   6. Summary (rich_text)
   7. Suggested Labels (rich_text)
   8. Status (select: Open, Closed)
   9. Source (select: ai, fallback)
   10. Created (date)

3. Kết nối Notion: Tạo internal integration tại notion.so/my-integrations. Thêm credential Notion vào n8n. Share database với integration (database → … → Connections → select integration).
4. Cấu hình Nodes: Trong node “When Issue Opened” — set Owner và Repository khớp với repo GitHub. Trong nodes “Verify Notion Duplicate” và “Add to Notion Board” — set Database tới Notion database của bạn. Thêm OpenRouter API key vào node “OpenAI Qwen-3 Model”.
5. Active: Bật workflow. Mở một test issue trên GitHub repo để kiểm tra.

---

4. Tùy chỉnh (Customization)

• Swap the LLM: Thay đổi model trong node “OpenAI Qwen-3 Model” thành bất kỳ model nào được OpenRouter hỗ trợ (GPT-4o, Claude, Gemini…). Hoặc trỏ sang model tự host bằng cách đổi base URL trong credential.
• Điều chỉnh luật triage: Chỉnh sửa prompt trong “Initiate AI Triage” để thêm category tùy chỉnh cho dự án của bạn (ví dụ: “performance”, “accessibility”, “security”). Model sẽ sử dụng bất kỳ định nghĩa nào bạn cung cấp trong prompt.
• Multi-repo: Nhân bản workflow cho mỗi repo bạn muốn triage, hoặc sửa trigger để dùng GitHub App theo dõi nhiều repositories.
• Thêm thông báo team: Sau node “Post GitHub Comment”, thêm node Slack hoặc Discord để gửi tóm tắt các issue ưu tiên cao đến team chat.
• Auto-assign: Thêm logic sau “Format AI Triage Results” để gán GitHub issue dựa trên category (ví dụ: bugs cho backend team, docs cho content team).
• Auto-label: Sử dụng suggested labels từ AI để tự động gắn labels trên GitHub issue. Yêu cầu tạo labels trong repo trước.

---

5. Hướng phát triển (What’s Next)

Workflow hiện tại được thiết kế như một nền tảng. Đây là những hướng mở rộng khi nhu cầu tăng lên:

A. Auto-label trên GitHub Sử dụng suggested labels từ AI để tự động gắn labels trên issue. Yêu cầu tạo labels trong repo trước, nhưng khi đã setup, loại bỏ thêm một bước thủ công nữa.

B. Batch Triage Thêm chế độ “Triage All Open Issues” xử lý các issue chưa triage hiện có theo lịch trình, không chỉ issue mới qua webhook. Hữu ích cho backfills hoặc khi áp dụng workflow trên repo đang hoạt động.

C. Priority-based Routing Issue ưu tiên cao nhận thông báo Slack hoặc Discord ngay lập tức. Ưu tiên trung bình và thấp chỉ vào Notion. SLA phản hồi khác nhau cho từng mức ưu tiên.

D. Learning từ Feedback Theo dõi khi con người thay đổi category do AI gán trong Notion. Sử dụng các sửa đổi đó làm few-shot examples trong prompt để cải thiện độ chính xác theo thời gian.

E. Notion Dashboard Xây dựng Notion view với filter theo category và priority. Thêm view “Triage backlog” sắp xếp theo priority để team luôn biết việc gì cần xử lý tiếp theo.

F. Multi-source Triage Mở rộng trigger để lắng nghe cả GitLab issues, Linear tickets hoặc email hỗ trợ khách hàng. Tất cả kết quả triage hội tụ vào cùng một Notion board.

Phiên bản hiện tại cố ý giữ đơn giản. Đơn giản nghĩa là chạy rẻ, ít lỗi, dễ debug. Độ phức tạp có thể thêm dần khi use case thực tế đòi hỏi.

---

6. Yêu cầu hệ thống (Requirements)

• n8n instance (self-hosted hoặc cloud)
• GitHub Fine-grained Personal Access Token (Issues read/write, Webhooks read/write)
• Notion account với internal integration
• OpenRouter API key (hoặc bất kỳ endpoint tương thích OpenAI nào)

⚠️ Lưu ý chi phí (Cost Warning): Workflow gọi OpenRouter API cho mỗi issue mới được mở. Với repository có tần suất issue thấp đến trung bình, chi phí rất nhỏ. Cơ chế duplicate check giúp tránh gọi API trùng lặp. Nếu repository có lượng issue lớn (hàng trăm/ngày), cân nhắc rate limit của OpenRouter và Notion API.