Token stage-only của npm: Bằng chứng cần lưu lại khi tách biệt tự động hóa triển khai và phê duyệt cuối cùng
Việc tách biệt quyền hạn của CI trong việc tạo gói và quyền công khai gói đó cho người dùng sẽ giúp trách nhiệm cuối cùng của đợt phát hành trở nên rõ ràng hơn. Tuy nhiên, việc chỉ thêm một nút phê duyệt không có nghĩa là rủi ro chuỗi cung ứng sẽ biến mất. Bạn phải bắt đầu bằng việc xác định rõ người phê duyệt cần kiểm tra những gì.
Vào ngày 18 tháng 9, GitHub đã thông báo rằng người dùng có thể chọn quyền ghi stage-only trên npm granular access token. Quy trình hoạt động là tự động hóa sẽ gửi phiên bản vào trạng thái chờ đánh giá, và người bảo trì sẽ phê duyệt việc công khai thông qua 2FA. Dưới đây là phần giải thích phân biệt giữa các thay đổi chính thức và các đề xuất từ ban biên tập để đưa tính năng này vào vận hành thực tế.
Chặn công khai trực tiếp khác với việc gỡ bỏ quyền ghi
Theo hướng dẫn chính thức, bạn có thể thực thi npm stage publish bằng token này, nhưng việc công khai trực tiếp qua npm publish sẽ bị từ chối. Giới hạn này vẫn được áp dụng ngay cả khi có cài đặt bỏ qua 2FA dành cho tự động hóa. Đây không phải là tính năng tự động thay đổi hành vi của các token hiện có mà được áp dụng tùy chọn.
Điểm cần lưu ý là các quyền ghi gói khác, chẳng hạn như chuyển đổi dist-tag và đánh dấu không dùng nữa (deprecation) cho phiên bản, vẫn còn tồn tại. Không nên hiểu cái tên stage-only là một token chỉ đọc hoặc hoàn toàn vô hại. Bạn vẫn phải quản lý phạm vi gói được cho phép, vị trí lưu trữ secret, chủ thể sử dụng và quy trình thu hồi token.
Xác định gói tài liệu phát hành để người phê duyệt đối chiếu
Nội dung dưới đây không phải là thiết lập bắt buộc của npm mà là đề xuất vận hành dành cho các nhóm nhỏ. Đối với mỗi yêu cầu phê duyệt, hãy đính kèm commit mã nguồn, gói và phiên bản đích, kết quả kiểm thử, danh sách tệp sẽ có trong gói và tóm tắt thay đổi. Nếu người phê duyệt phải tự thu thập bằng chứng từ nhiều vị trí log CI khác nhau, việc đánh giá rất dễ trở thành những cú nhấp chuột mang tính hình thức.
Đặc biệt, việc xem xét mã nguồn và kiểm tra tệp phân phối là hai việc hoàn toàn khác nhau. Những tệp không có trong kho lưu trữ có thể bị đưa vào trong quá trình build, hoặc những tệp cần thiết có thể bị bỏ sót. Nhóm có thể thiết lập nguyên tắc lập tài liệu đánh giá dựa trên các artifact thực tế được gửi lên, và nếu artifact bị thay đổi sau khi đã đánh giá, nó phải được coi là một đối tượng đánh giá mới.
Vẫn có trạng thái chờ sau khi CI báo xanh
Nếu quy trình tự động hóa trước đây báo cáo việc lệnh chạy thành công là đã hoàn tất phát hành, bạn cần thay đổi cách thể hiện trạng thái trước tiên. Hãy phân chia rõ ràng thành: đã gửi xong, chờ phê duyệt và đã công khai hoàn tất, đồng thời ghi lại căn cứ xác nhận cho từng giai đoạn. Trong thông báo, việc nêu rõ giai đoạn hiện tại và người phụ trách sẽ hữu ích cho người vận hành hơn là chỉ dùng một từ "thành công" đơn thuần.
Lấy một ví dụ giả định: nếu CI chạy ban đêm gửi phiên bản mới nhưng người phụ trách chỉ xem xét vào ngày hôm sau, thì không được gửi thông báo phát hành đến người dùng tại thời điểm vừa gửi phiên bản. Hãy liên kết để tài liệu hoặc thông báo được tiếp nối sau khi đã xác nhận công khai theo quy định của nhóm. Nhóm cũng cần thống nhất trước về việc ai sẽ đánh giá khi hàng đợi bị tồn đọng và khi nào cần dọn dẹp các bản gửi trước đó.
Xác thực việc chuyển đổi với một gói nhỏ
Hiện tại, các điều kiện tiên quyết trong hướng dẫn chính thức bao gồm gói npm hiện có, quyền công khai gói, 2FA của tài khoản, npm CLI 11.15.0 trở lên và Node.js 22.14.0 trở lên. Trước khi thực hiện chuyển đổi thực tế, bạn nên kiểm tra lại tài liệu mới nhất và rà soát phiên bản runner đang sử dụng.
Trước hết, chúng tôi khuyên bạn nên giới hạn phạm vi token trên một gói có mức độ ảnh hưởng thấp và thực hành toàn bộ quy trình: từ gửi staging, người bảo trì đánh giá cho đến xác nhận kết quả công khai. Nếu khi gặp lỗi mà bạn lại lập tức chuyển hướng sang token cũ có quyền hạn rộng hơn thì ranh giới đã phân tách sẽ trở nên vô nghĩa. Hệ thống cũng cần có khả năng xử lý việc phê duyệt bị trì hoãn như một trạng thái bình thường.
Những câu hỏi khi so sánh với trusted publishing
npm cũng cung cấp tính năng trusted publishing sử dụng OIDC. Trước tiên, bạn cần xem xét liệu tính năng đó có phù hợp với môi trường CI được hỗ trợ và phương thức phê duyệt của nhóm hay không, và không có lý do gì để coi token stage-only là giải pháp tối hậu cho mọi nhóm. Nếu quy trình tự động hóa của bạn bắt buộc phải tiếp tục dùng token, điều này có thể được xem như bạn đã có thêm một lựa chọn để chuyển đổi từng bước.
Thông báo chính thức đặt ra mục tiêu vào tháng 1 năm 2027 sẽ loại bỏ khả năng công khai trực tiếp của các token bypass-2FA. Thay vì phỏng đoán mọi chi tiết triển khai đã được ấn định, việc thiết thực hơn lúc này là lập danh sách các workflow thuộc diện áp dụng và người phụ trách chuyển đổi. Bạn nên theo dõi các thông báo chính thức sau này để biết lịch trình có thay đổi hay không.
Khi quyết định có nên áp dụng hay không
Bài viết này không khẳng định sự đồng thuận rộng rãi trong cộng đồng hay tỷ lệ giảm thiểu sự cố thực tế. Đây là đề xuất về các quy trình vận hành có thể đánh giá được dựa trên hành vi chính thức của tính năng mới. Điểm khởi đầu để quyết định áp dụng là bạn có thể giải thích rõ ràng công việc nào do tự động hóa đảm nhận và việc nào cần con người xác minh hay không.
Những việc bạn có thể làm ngay hôm nay là tìm xem token phát hành hiện đang được sử dụng ở đâu, ghi lại các điều kiện xác định việc công khai đã hoàn tất, và quy định các bằng chứng cần thiết cho mỗi lần phê duyệt. Chỉ khi việc giới hạn quyền hạn đi đôi với chất lượng đánh giá thì bước staging mới thực sự mang lại hiệu quả.