Tự động hóa tài liệu kỹ thuật liên kho (cross-repo) với GitHub Agentic Workflows

Đối với nhiều đội ngũ phát triển sản phẩm, câu hỏi “Tài liệu đâu rồi?” luôn là một áp lực. Thông thường, tài liệu thường bị chậm trễ so với tiến độ phát hành tính năng. Đội ngũ Aspire (nhóm xây dựng công cụ cho các ứng dụng phân tán) đã giải quyết vấn đề này bằng cách tận dụng GitHub Agentic Workflows để tự động hóa quy trình tạo tài liệu kỹ thuật mà không làm ảnh hưởng đến các tiêu chuẩn bảo mật khắt khe.

Thách thức của tự động hóa liên kho (cross-repo)

Vấn đề nằm ở chỗ mã nguồn sản phẩm và trang tài liệu thường nằm ở hai kho (repository) khác nhau, với quy trình review và triển khai riêng biệt. Việc cấp quyền ghi (write access) rộng rãi cho các tác nhân tự động là một rủi ro bảo mật. Đội ngũ Aspire cần một giải pháp có thể tương tác giữa các repo mà không cần đến các token có quyền hạn quá mức.

Giải pháp: GitHub Agentic Workflows

GitHub Agentic Workflows cho phép định nghĩa quy trình dưới dạng một tệp Markdown chứa các hướng dẫn bằng ngôn ngữ tự nhiên. Điểm mấu chốt là cơ chế safe-outputs handler: tác nhân (agent) không trực tiếp ghi dữ liệu lên GitHub mà chỉ phát đi “ý định” (intent). Một quy trình riêng biệt, được giới hạn quyền hạn nghiêm ngặt, sẽ thực hiện các hành động này sau khi đã qua kiểm duyệt.

Quy trình vận hành hiệu quả

Quy trình của Aspire hoạt động dựa trên các bước cụ thể:

• Xác định nhánh mục tiêu: Sử dụng Milestone của pull request để ánh xạ chính xác nơi tài liệu cần được cập nhật.
• Tạo bản nháp tài liệu: Agent phân tích diff của code, kiểm tra các issue liên quan và soạn thảo nội dung tài liệu theo chuẩn MDX.
• Review bởi chuyên gia (SME): Tài liệu được tạo dưới dạng một pull request nháp. Người review chính là kỹ sư đã thực hiện tính năng đó, đảm bảo tính chính xác về mặt kỹ thuật.
• Bảo mật: Mỗi workflow được cấp một GitHub App token riêng biệt, chỉ có quyền truy cập vào các repo được chỉ định và bị chặn truy cập vào các tệp nhạy cảm như cấu hình bảo mật hay file quản lý dependency.

Kết quả đạt được

Trong giai đoạn thử nghiệm, đội ngũ đã ghi nhận 82 pull request tài liệu được tạo tự động với thời gian merge trung bình chỉ khoảng 44,8 giờ sau khi tính năng được merge. Quan trọng hơn, quy trình này không thay thế các chuyên gia viết tài liệu mà giúp họ giải phóng khỏi các công việc lặp đi lặp lại, tập trung vào việc xây dựng nội dung chuyên sâu và hướng dẫn người dùng.

Việc áp dụng các ràng buộc bảo mật mạnh mẽ không làm hệ thống trở nên khó sử dụng, mà ngược lại, giúp quy trình tự động hóa trở nên đáng tin cậy và chính xác hơn. Đây là hướng đi tiềm năng cho các đội ngũ đang đối mặt với bài toán quản lý tài liệu trong môi trường phát triển phức tạp.

Nguồn tham khảo: GitHub Blog