Tự động hóa tài liệu liên kho lưu trữ bằng Quy trình làm việc tác nhân của GitHub

“Tài liệu ở đâu?” Đây là câu hỏi không thành viên nào trong nhóm sản phẩm muốn trả lời. Câu trả lời trung thực thường là một biến thể của “đang bị chậm trễ”. Một người viết đang nhìn vào một pull request đã đóng, cố gắng tìm hiểu ngược lại những gì đã thay đổi. Tác giả của pull request đã chuyển sang công việc khác. Đế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 trạng của chúng tôi trong nhóm Aspire (chúng tôi là một nhóm nhỏ gồm 10 người xây dựng công cụ dành cho nhà phát triển cho các ứng dụng phân tán). Vài tháng trước, chúng tôi đang 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 đã tin cậy một cách an toàn. Đó là lúc chúng tôi phát hiện ra GitHub Agentic Workflows. Tôi bắt đầu gắn các nguyên mẫu vào microsoft/aspire. Đây là những gì chúng tôi đạt được, với các con số được 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 bình là 44,8 giờ sau pull request sản phẩm, mỗi pull request đều được kỹ sư phát hành tính năng đó xem xét. 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 để đặt câu hỏi “ai viết cái này?”. 🔒 Hạn chế: tự động hóa đa kho lưu trữ là phần khó khăn 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 – kho lưu trữ, mục tiêu triển khai và chuỗi xem xét khác nhau. Hầu hết các nhóm đều nhanh chóng tìm ra cách tự động hóa trong cùng một kho lưu trữ; tự động hóa đa kho lưu trữ là nơi mọi thứ trở nên phức tạp. Các token có phạm vi kho lưu trữ rộng lớn thuộc về viện bảo tàng, và bất kỳ chính sách bảo mật có trách nhiệm nào (bao gồm cả của chúng tôi) đều hạn chế chúng một cách phù hợp. Đó là một điều tốt. Đó cũng là một nút thắt cổ chai 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ã. Quy trình làm việc mặc định trong nhiều năm là: Kỹ sư phát hành một tính năng trong microsoft/aspire. Người viết tài liệu nhận thấy vài tuần sau đó. Người viết tài liệu mở pull request, đọc sự khác biệt và liên hệ với kỹ sư để làm rõ những gì đã thay đổi. Kỹ sư đang làm tính năng tiếp theo, nhớ mang máng, trả lời với một nửa thông tin. Bản nháp tài liệu được phát hành, đôi khi chống lại một bản phát hành đã có sẵn. Đây là cái giá của việc tìm hiểu ngược. Chúng tôi cần 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 một token có quyền ghi mọi nơi. GitHub Agentic Workflows hóa ra là câu trả lời. 🤖 Tại sao lại là GitHub Agentic Workflows GitHub Agentic Workflows là một dự án từ nhóm GitHub Next mà tôi vẫn thường mô tả với mọi người là “GitHub Actions, nhưng với một mô hình làm bộ xử lý tác vụ và các rào cản bảo vệ đáp ứng yêu cầu đánh giá bảo mật”. Điều đó có vẻ giản lược, nhưng khá gần. Cấu trúc của nó: Bạn tạo một quy trình làm việc dưới dạng một tệp markdown duy nhất (.github/workflows/my-thing.md). Phần đầu theo kiểu YAML, bên dưới là một lời nhắc bằng tiếng Anh. Bạn chạy biên dịch GitHub Agentic Workflows, và nó tạo ra một tệp .lock.yml (một quy trình làm việc GitHub Actions thông thường) mà bạn cam kết cùng. Khi chạy, quy trình làm việc chạy một tác nhân dựa trên lời nhắc của bạn với một bộ công cụ bị hạn chế. Điều quan trọng là tác nhân không ghi trực tiếp vào GitHub. Nó phát ra ý định (một khối JSON mô tả các pull request, vấn đề và bình luận mà nó muốn tạo), và một công việc riêng biệt, có phạm vi hẹp (trình xử lý đầu ra an toàn) hiện thực hóa ý định đó thông qua một ứng dụng GitHub cho mỗi quy trình làm việc. Điểm cuối cùng đó là chìa khóa. Tác nhân có quyền đọc và một lời nhắc. Các thao tác ghi đi qua một quy trình nhỏ có thể kiểm chứng với các danh sách cho phép rõ ràng. Đánh giá bảo mật chấp thuận. Chúng tôi phát hành. 💚 Một lưu ý nhỏ: các ngăn xếp tương tự Tôi đánh giá cao khi các công cụ được sử dụng để xây dựng lại được xây dựng bằng chính những công cụ đó. Tài liệu GitHub Agentic Workflows được xây dựng bằng Astro và Starlight. Tương tự, aspire.dev cũng sử dụng Astro với Starlight, được bổ sung bởi hệ sinh thái plugin Starlight rộng lớn hơn (astro-mermaid, starlight-llms-txt, starlight-sidebar-topics, starlight-image-zoom, chủ đề @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ự gắn kết thực sự ở đây. Công cụ chúng tôi sử dụng để tự động hóa tài liệu và trang web tài liệu mà chúng tôi tự động hóa đều có cùng một nền tảng. Điều này tiện lợi, vì sơ đồ trình tự Mermaid trong phần tiếp theo hiển thị chính xác như nhau ở cả hai môi trường. Quy trình đầu cuối Đây là quy trình chúng tôi đã áp dụng. Nhân vật chính là một quy trình làm việc 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 merged == true. Từ đó, quy trình làm việc đầu tiên chạy một bộ giải quyết nhánh đích xác định bằng bash thuần túy trước khi tác nhân (agent) hoạt động: Tiêu đề mốc của pull request (ví dụ: 13.4 → release/13.4 trên aspire.dev). Tiêu đề mốc của vấn đề được liên kết (phân tích Fixes/Closes/Resolves #N từ nội dung, tìm nạp từng vấn đề, lấy mốc đầu tiên không trống). Tham chiếu cơ sở của pull request, nếu nó khớp với release/X.Y[.Z]. Trở về main. Đây là điểm mấu chốt. Các mốc trong kho sản phẩm ánh xạ rõ ràng tới các nhánh phát hành trong kho tài liệu. Khi tác nhân cuối cùng chạy, nó biết chính xác nơi tài liệu nên được đặt mà không cần phải viết sáng tạo về các nhánh đích hoặc đoán mò. Tác nhân đọc sự khác biệt, quét các vấn đề được liên kết và quyết định: liệu điều này có cần tài liệu không? Nếu có, nó sẽ soạn thảo nội dung thực tế trong một không gian làm việc microsoft/aspire.dev đã được kiểm tra, 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, thành phần Starlight). Sau đó, nó phát ra một đầu ra an toàn create_pull_request và chuyển giao. Trình xử lý đầu ra an toàn tiếp quản: Tiền tố tiêu đề: [docs] Nhãn: docs-from-code draft: true (chúng tôi không bao giờ tự động hợp nhất) Nhánh cơ sở: do tác nhân cung cấp, giới hạn ở main hoặc release/* Kho đích: microsoft/aspire.dev Người đánh giá: SME được xác định từ các đánh giá của pull request nguồn – tức là, bất kỳ ai mà nhóm sản phẩm tin tưởng để phê duyệt tính năng, giờ đây được yêu cầu phê duyệt tài liệu cho tính năng đó. Một công việc đi kèm sẽ đăng một bình luận đánh dấu trở lại trên pull request nguồn với liên kết pull request tài liệu và giảm thiểu bất kỳ pr-docs-check cũ hơn nào.