Tự động hóa tài liệu liên kho lưu trữ với GitHub Agentic Workflows

Khám phá cách đội ngũ Aspire biến các thay đổi sản phẩm đã hợp nhất thành các pull request tài liệu được SME (chuyên gia chuyên môn) đánh giá, từ đó thu hẹp khoảng cách giữa việc phát hành và viết tài liệu.

Ngày 8 tháng 7 năm 2026

9 phút

“Tài liệu đâu rồi?” Đây là câu hỏi mà không ai trong đội ngũ sản phẩm muốn trả lời. Câu trả lời thành thật thường là một biến thể của cụm từ “đang bị chậm tiến độ”. Một người viết tài liệu đang nhìn chằm chằm vào một pull request đã đóng, cố gắng tìm hiểu ngược lại những gì đã thay đổi. Người tạo pull request thì đã chuyển sang việc khác từ lâu. Đến khi tài liệu thực sự được xuất bản, tính năng đó đã được phát hành, đôi khi là nhiều lần.

Đó từng là tình cảnh của chúng tôi tại đội ngũ Aspire (chúng tôi là một nhóm nhỏ gồm 10 người đang xây dựng các công cụ phát triển cho các ứng dụng phân tán). Vài tháng trước, chúng tôi đã cố gắng tìm cách đưa AI vào các quy trình tự động hóa mà chúng tôi vốn tin tưởng một cách an toàn. Đó là lúc chúng tôi khám phá ra GitHub Agentic Workflows. Tôi bắt đầu tích hợp các bản mẫu vào microsoft/aspire.

Đây là những gì chúng tôi đạt được, với các con số lấy trực tiếp từ GitHub: đối với Aspire 13.3 và 13.4, 82 pull request tài liệu tính năng đã được hợp nhất với thời gian trung vị là 44,8 giờ sau pull request sản phẩm, tất cả đều được đánh giá bởi chính kỹ sư đã phát hành tính năng đó. Không cần thêm nhân sự. Không cần đào tạo lại quy trình. Chỉ là một cách khác để trả lời câu hỏi “ai là người viết tài liệu này?”

🔒 Rào cản: tự động hóa liên kho (cross-repo) là phần khó nhất

Sản phẩm của chúng tôi nằm trong microsoft/aspire và trang tài liệu của chúng tôi nằm trong microsoft/aspire.dev—khác kho lưu trữ, khác mục tiêu triển khai và khác chuỗi đánh giá. Hầu hết các đội ngũ đều tìm ra cách tự động hóa trong cùng một kho lưu trữ khá nhanh chóng; nhưng tự động hóa liên kho mới là nơi mọi thứ trở nên phức tạp. Các token có phạm vi truy cập rộng trên kho lưu trữ nên được đưa vào bảo tàng, và bất kỳ tư thế bảo mật có trách nhiệm nào (bao gồm cả chúng tôi) đều hạn chế chúng một cách tương ứng. Đó là một điều tốt. Nhưng nó cũng là một nút thắt thực sự nếu nơi bạn viết tài liệu không phải là nơi bạn viết mã nguồn.

Quy trình mặc định trong nhiều năm là:

Đây là cái giá phải trả cho việc tìm hiểu ngược lại (reverse-engineering). Chúng tôi cần một hệ thống tự động hóa có thể vượt qua các kho lưu trữ mà không cần cấp cho một tác nhân (agent) quyền truy cập ghi vào mọi nơi. GitHub Agentic Workflows hóa ra lại là câu trả lời.

🤖 Tại sao lại là GitHub Agentic Workflows

GitHub Agentic Workflows là một dự án từ đội ngũ GitHub Next mà tôi vẫn thường mô tả với mọi người là “GitHub Actions, nhưng có thêm một mô hình đóng vai trò xử lý các mục công việc và các rào cản bảo mật đáp ứng được yêu cầu đánh giá”. Cách nói đó có phần đơn giản hóa, nhưng khá sát thực tế.

Hình thái của nó:

Gạch đầu dòng cuối cùng đó chính là chìa khóa mở ra giải pháp. Tác nhân nhận quyền đọc và một câu lệnh (prompt). Các thao tác ghi được thực hiện thông qua một đường ống (pipeline) nhỏ có thể kiểm chứng với danh sách cho phép (allow-list) rõ ràng. Đánh giá bảo mật được thông qua. Chúng tôi phát hành.

💚 Một lưu ý nhỏ: các hệ sinh thái đồng điệu

Tôi thích khi các công cụ bạn dùng để xây dựng lại được tạo ra bằng chính những công cụ mà bạn đang sử dụng. Tài liệu của GitHub Agentic Workflows được xây dựng bằng Astro và Starlight. aspire.dev cũng vậy—Astro kết hợp với Starlight, được trang trí bằng hệ sinh thái plugin Starlight rộng lớn hơn (astro-mermaid, starlight-llms-txt, starlight-sidebar-topics, starlight-image-zoom, theme @catppuccin/starlight tuyệt đẹp, và nhiều hơn nữa. Xin gửi lời cảm ơn đến Chris Swithinbank và những người duy trì Starlight, toàn bộ hệ sinh thái này mang lại cảm giác được thiết kế bởi những người thực sự quan tâm).

Có một sự tương đồng thực sự ở đây. Công cụ chúng tôi dùng để tự động hóa tài liệu và trang tài liệu mà chúng tôi tự động hóa vào đó chia sẻ cùng một nền tảng. Thật tiện lợi, vì sơ đồ trình tự Mermaid trong phần tiếp theo hiển thị hoàn toàn giống nhau trong cả hai thế giới.

Đường ống (pipeline) từ đầu đến cuối

Đây là quy trình mà chúng tôi đã chốt. Nhân vật chính là một workflow có tên pr-docs-check.md nằm trong microsoft/aspire.

Một lần chạy bắt đầu khi pull_request: closed đối với main hoặc release/*, được kiểm soát bởi điều kiện merged == true. Từ đó, workflow trước tiên chạy một trình giải quyết nhánh mục tiêu tất định bằng bash thuần trước khi tác nhân được kích hoạt:

Đây là chốt chặn quan trọng. Các cột mốc (milestone) trong kho sản phẩm ánh xạ rõ ràng tới các nhánh phát hành (release branch) trong kho tài liệu. Khi tác nhân thực sự chạy, nó biết chính xác tài liệu nên được đưa vào đâu mà không cần phải suy đoán hay viết lách sáng tạo về các nhánh mục tiêu.

Tác nhân đọc diff, quét các vấn đề (issue) được liên kết và quyết định: tính năng này có cần tài liệu không? Nếu có, nó soạn thảo nội dung thực tế trong một không gian làm việc microsoft/aspire.dev đã được checkout, tuân theo kỹ năng viết tài liệu hiện có của chúng tôi (giọng văn, quy ước MDX, các thành phần Starlight). Sau đó, nó xuất ra một safe-output create_pull_request và bàn giao lại.

Trình xử lý safe-outputs tiếp quản:

Một tác vụ đi kèm sẽ đăng một bình luận đánh dấu (marker comment) quay lại pull request nguồn với liên kết đến pull request tài liệu và thu gọn bất kỳ bình luận pr-docs-check cũ nào nếu chạy lại. Kỹ sư vừa nhấn Merge sẽ nhận được thông báo trong vòng vài phút: “Đây là bản nháp tài liệu. Bạn xem qua nhé?”

🔐 Hợp đồng safe-outputs

Toàn bộ câu chuyện bảo mật nằm ở một đoạn frontmatter nhỏ, đơn giản:

Đó là thỏa thuận bằng văn bản thuần túy. Tác nhân nhận được một token GitHub App mà việc cài đặt của nó chỉ giới hạn trong đúng hai kho lưu trữ—kho sản phẩm và kho tài liệu—và không thể truy cập bất cứ thứ gì khác trong tổ chức. Nó chỉ có thể tạo pull request vào main hoặc release/*. AGENTS.md và các tệp kê khai phụ thuộc (dependency manifests) đều nằm ngoài giới hạn theo chính sách. Nếu việc tạo pull request thất bại (lỗi mạng, xung đột, bất cứ điều gì), khung làm việc sẽ chuyển sang tạo một issue, vì vậy không có gì bị bỏ sót một cách âm thầm.

Đây là phần mà bộ phận đánh giá bảo mật thực sự hài lòng. Lập luận của tác nhân có thể mơ hồ, nhưng bề mặt thao tác (action surface) thì không.

📊 Theo các con số

Dưới đây là các số liệu thống kê từ cửa sổ 30 ngày gần nhất (3 tháng 5 – 2 tháng 6 năm 2026) bao gồm giai đoạn cuối của bản phát hành Aspire 13.3 và giai đoạn chuẩn bị cho 13.4:

Lưu ý: Các con số được ghi lại tại thời điểm viết bài; các workflow vẫn tiếp tục chạy, vì vậy tổng số chỉ có tăng lên.

Một vài con số trong đó xứng đáng được xem xét kỹ hơn:

✅ Những gì hiệu quả, ❌ những gì chưa hiệu quả

Những gì hiệu quả

Những gì chưa hiệu quả (lúc đầu)

Tổng kết

Những thay đổi chúng tôi thực hiện đã thay đổi tư duy của chúng tôi. Một tính năng không được coi là hoàn thành cho đến khi tài liệu đã xong. Tài liệu không còn theo sau như một cái lon buộc vào đuôi xe. Đánh giá của kỹ sư là chốt chặn; bot thực hiện việc gõ phím.

Quan trọng hơn, điều này không thay thế người viết tài liệu; nó giúp họ giảm bớt gánh nặng. Các cây bút của chúng tôi từng dành phần lớn thời gian để tìm hiểu ngược lại các tính năng. Giờ đây, họ dành thời gian cho những việc mà chỉ con người mới làm tốt: các trang tường thuật, chương trình mẫu, hướng dẫn khái niệm, những phần tài liệu không thể tự động tạo ra từ một bản diff. Bot xử lý công việc cơ học như “tùy chọn mới này đã được thêm vào; đây là bản cập nhật trang tham chiếu” – công việc vốn chưa bao giờ thú vị với bất kỳ ai.

Gửi lời cảm ơn to lớn đến đội ngũ GitHub Next vì GitHub Agentic Workflows (và vì đã biến safe-outputs thành một phần thiết kế cốt lõi), và đến Chris Swithinbank cùng những người duy trì Starlight vì nền tảng tài liệu mà chúng tôi tự động hóa vào đó. Cũng xin gửi lời cảm ơn chân thành đến các chuyên gia bảo mật, những người có các rào cản đã buộc chúng tôi phải thiết kế hệ thống này đúng cách ngay từ đầu. Bí mật nhàm chán của tự động hóa tốt là các ràng buộc bảo mật chặt chẽ làm cho hệ thống trở nên đáng tin cậy và chính xác hơn.