Act: chạy GitHub Actions trên máy cá nhân để bắt lỗi workflow sớm hơn
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
Chạy workflow GitHub Actions ngay trên máy cá nhân: act trong ba phút đọc
Act là công cụ dòng lệnh viết bằng Go để chạy các workflow GitHub Actions ở máy cục bộ. README tóm gọn bằng khẩu hiệu "Think globally, act locally" và nêu hai lý do dùng: có phản hồi nhanh mà không cần commit rồi đẩy lên mỗi lần sửa tệp workflow, và dùng các workflow làm công cụ chạy tác vụ cục bộ thay cho Makefile. [1]
Bài viết xét công cụ này cho bộ phận công nghệ thông tin của một công ty phân phối dược phẩm ở Việt Nam, đội viết và bảo trì tập lệnh tích hợp giữa các hệ thống kho, kế toán và đối soát. Khuyến nghị: act đáng thử như công cụ hỗ trợ lập trình viên kiểm tra trước workflow, nhưng không nên coi kết quả chạy cục bộ là bằng chứng chính thức cho quy trình kiểm soát thay đổi. Môi trường cục bộ chỉ được dự án mô tả là cấu hình để khớp với GitHub, không phải là hệ thống tương đương hoàn toàn. [1]
Cần biết trước ba điều. Một, act phụ thuộc Docker để chạy container cho các bước. [1] Hai, dự án còn ở dòng phiên bản 0.2.x với bản phát hành gần nhất trong dữ liệu thu thập vào đầu tháng 6 năm 2026. Ba, một số tài liệu trong kho khá cũ, như danh sách ảnh runner nhắc tới Ubuntu 18.04 và ảnh dừng cập nhật từ năm 2020. [4]
Giấy phép gốc là MIT, kèm các tệp giấy phép khác trong thư mục con. [2][6][7]
Vòng lặp commit, push, chờ và đoán lỗi
Ai từng viết một workflow CI đều biết nhịp quen thuộc: sửa tệp YAML, commit, đẩy lên, chờ runner nhận việc, đọc nhật ký, rồi lặp lại. Mỗi vòng có thể mất vài phút và để lại lịch sử đầy commit sửa vặt. README gọi đây là điều cần tránh khi nói về phản hồi nhanh cho các thay đổi trong thư mục .github/workflows hoặc cho các hành động nhúng. [1]
Với một đội IT trong công ty phân phối, vấn đề có thêm một lớp: tập lệnh liên quan tới dữ liệu lô, hạn dùng và đối soát tồn kho, nên lỗi gây ra khi chạy trên hệ thống thật tốn kém hơn nhiều so với lỗi ở một ứng dụng thử nghiệm. Đội muốn bắt lỗi cú pháp, thiếu biến hoặc sai thứ tự bước trước khi đụng tới nhánh chính. Đây là mô tả nhu cầu của bài viết, không phải tuyên bố của dự án.
Cách dùng thứ hai trong README là thay Makefile: tác giả viết rằng mình thích make nhưng ghét lặp lại, nên muốn dùng chính các GitHub Actions đã khai báo cho tác vụ cục bộ. [1] Với một đội đã có workflow, điều này tránh phải bảo trì hai bản mô tả cùng một quy trình.
Từ tệp YAML tới Plan, Stage, Run và chuỗi Executor
README chỉ mô tả ở mức tổng quan: act đọc workflow trong thư mục .github/workflows, xác định tập hành động cần chạy, dùng Docker API để kéo hoặc dựng ảnh mà workflow yêu cầu, suy ra đường thực thi theo phụ thuộc đã khai báo, rồi chạy container cho từng hành động. [1] Muốn hiểu sâu hơn phải đọc tệp hướng dẫn kiến trúc nằm trong kho, dành cho các công cụ hỗ trợ lập trình. [3]
Tệp đó mô tả luồng thực thi gồm năm lớp. Giao diện dòng lệnh dựa trên Cobra đọc cờ vào một cấu trúc Input. Bộ lập kế hoạch phân tích YAML thành một Plan gồm các Stage chạy tuần tự, mỗi Stage chứa các Run chạy song song, tức các job. Bộ chạy (runner) biến Plan thành chuỗi Executor. RunContext giữ toàn bộ trạng thái của một job như biến môi trường, ma trận, container và biểu thức. Mỗi loại bước (hành động, docker, tập lệnh) hiện thực một giao diện step. [3]
Mẫu thiết kế đặc trưng là Executor: một hàm nhận context và trả lỗi, ghép lại bằng các phép như Then, Finally, OnError, chạy tuần tự hoặc song song, có điều kiện. [3] Với người đánh giá, điều này giải thích cách một job được dựng bằng việc ghép các hàm nhỏ, và là điểm vào hợp lý nếu đội muốn đọc mã.
Các gói chính còn gồm gói mô hình cho việc phân tích YAML, gói container bọc Docker API và cũng có môi trường thực thi trên máy chủ, gói exprparser diễn giải ngôn ngữ biểu thức dạng dấu đô-la ngoặc nhọn của GitHub Actions, cùng gói artifacts và artifactcache cho máy chủ tải lên, tải xuống và bộ nhớ đệm. [3]
Hành trình của một job: biểu thức, container và biến môi trường
Theo dõi một job trong workflow kiểm tra tập lệnh đối soát. Lệnh act nhận cờ, tạo Input, rồi bộ lập kế hoạch đọc các tệp YAML và dựng Plan. [3] Theo mô tả, các Run trong cùng Stage chạy song song còn các Stage chạy tuần tự, nên job phụ thuộc nhau hẳn nằm ở các Stage khác nhau (đây là suy luận). [3]
Với mỗi job, RunContext gom biến môi trường và ma trận, đánh giá các biểu thức, rồi bộ chạy gọi lớp container để dựng hoặc kéo ảnh và chạy bước. [3][1] README nói biến môi trường và hệ thống tệp được cấu hình để khớp với những gì GitHub cung cấp. [1] Câu này là cam kết ý định; chưa có tài liệu đã đọc liệt kê mọi điểm khác biệt, nên mức khớp thực tế phải kiểm tra bằng thử nghiệm.
Các hành động có thể là cục bộ, từ xa, docker, composite hoặc workflow dùng lại. [3] Hành động từ xa nghĩa là phải lấy mã từ nơi khác về, tức có lưu lượng ra Internet tùy workflow. Bài này suy ra điều đó từ phân loại trong tài liệu kiến trúc, không từ mô tả chi tiết.
Những gì README và tài liệu nội bộ xác nhận
Chức năng cốt lõi, theo README, là chạy workflow từ thư mục .github/workflows bằng Docker, với biến môi trường và hệ thống tệp khớp với GitHub. [1] Dự án cũng giới thiệu một tiện ích mở rộng cho Visual Studio Code của bên thứ ba cho phép quản lý và chạy act ngay trong trình soạn thảo; đó là sản phẩm riêng, không thuộc kho này. [1]
Tài liệu kiến trúc liệt kê phạm vi mà bộ chạy xử lý: hành động cục bộ và từ xa, hành động docker, hành động composite và workflow dùng lại. [3] Mã gồm bộ diễn giải biểu thức của GitHub Actions và máy chủ artifact cùng bộ nhớ đệm. [3] Môi trường thực thi gồm cả container và máy chủ (host), theo mô tả gói container. [3]
Về ảnh: IMAGES.md liệt kê các ảnh có thể dùng, gồm ảnh node dựa trên Debian, các ảnh catthehacker/ubuntu với nhãn act-latest, act-22.04, act-20.04, act-18.04, và nhóm ảnh dựa trên môi trường ảo của GitHub. [4] Tài liệu kèm cảnh báo rằng kích thước hiển thị là kích thước nén trong registry, còn kích thước sau khi kéo về khác nhiều. [4]
Phần cần tách riêng: các ảnh catthehacker là dự án khác, và ảnh nektos/act-environments-ubuntu được ghi là cập nhật lần cuối vào tháng 2 năm 2020. [4] Những mục này là danh sách tham khảo, không phải cam kết hỗ trợ. Hướng dẫn người dùng đầy đủ nằm ở trang nektosact.com mà bài này chưa đọc. [1]
Ai thật sự cần chạy workflow trên máy mình
Người hưởng lợi rõ nhất là lập trình viên viết hoặc sửa workflow thường xuyên. Họ muốn thử trước khi đẩy lên, đúng kịch bản README mô tả. [1] Người thứ hai là kỹ sư DevOps muốn dùng chung một mô tả công việc cho cả CI và tác vụ cục bộ. [1]
Người thứ ba là người đóng góp cho chính act: CONTRIBUTING mô tả cách dùng act để chạy bước lint của chính dự án, một dạng tự dùng sản phẩm của mình. [5] Điều này không chứng minh chất lượng, nhưng cho thấy dự án có dùng công cụ trong quy trình của họ.
Không phù hợp: đội không dùng GitHub Actions, vì act xoay quanh định dạng workflow này; đội không thể chạy Docker trên máy làm việc; hoặc đơn vị cần bằng chứng chính thức cho kiểm soát thay đổi, vì lúc đó cần kết quả từ hệ thống CI chính. Với đội không có workflow nào, act chưa mang lại giá trị.
Giả định: bộ phận CNTT của một công ty phân phối dược phẩm
Dưới đây là tình huống giả định để đánh giá, không phải một ca đã xảy ra. Một công ty phân phối dược phẩm cấp vùng có đội IT bốn người, duy trì các tập lệnh đồng bộ danh mục sản phẩm giữa phần mềm quản lý kho, kế toán và cổng đặt hàng của nhà thuốc, cùng báo cáo đối soát số lô và hạn dùng. Mã nằm trên GitHub, mỗi thay đổi đi qua pull request với workflow kiểm tra tự động.
Điểm đau: workflow kiểm tra kiểu dữ liệu và chạy bộ thử nghiệm đối soát, nhưng mỗi lần sửa phải đẩy lên mới biết lỗi, và lịch sử đầy commit vặt. Đề xuất: mỗi lập trình viên dùng act để chạy job kiểm tra trên máy trước khi mở pull request. [1] Một số tác vụ lặp lại, như dựng gói hoặc định dạng mã, có thể gọi bằng chính workflow thay cho Makefile. [1]
Ranh giới an toàn đề xuất: dữ liệu thật về lô hàng, giá, thông tin khách hàng không đưa vào máy cá nhân để chạy thử; dùng bộ dữ liệu mẫu đã ẩn danh trong thư mục kiểm thử. Bí mật kết nối đến phần mềm kho không để trong tệp workflow. Tài liệu đã đọc không mô tả cách act xử lý bí mật, nên đội phải đọc hướng dẫn chính thức trước khi định cách truyền.
Docker, ảnh runner và sự lệch giữa máy cục bộ với runner thật
Triển khai act là cài một tệp thực thi và bảo đảm Docker chạy được trên máy. README hướng dẫn xây từ mã nguồn với Go từ phiên bản 1.20, dùng make test để chạy thử nghiệm và make install để cài. [1] Tệp hướng dẫn nội bộ lại ghi Go 1.24 trở lên. [3] Hai con số này khác nhau nên đội cần kiểm tra tệp mô-đun Go khi tự xây.
Quyết định vận hành quan trọng nhất là chọn ảnh. IMAGES.md liệt kê nhiều lựa chọn từ ảnh nhẹ dựa trên Debian đến ảnh lớn mô phỏng môi trường GitHub; ảnh nhẹ không có sẵn một số công cụ, ví dụ ghi chú nói các ảnh node bản slim không cài python. [4] Ảnh càng nhẹ càng cần tự cài thêm công cụ; ảnh càng đầy đủ càng tốn dung lượng. Đây là đánh đổi mà bài viết không đo được.
Nên ghim phiên bản act và ảnh bằng thẻ cụ thể, ghi vào tài liệu nội bộ, để mọi người chạy cùng một cấu hình. Đây là khuyến nghị của bài viết. Với CONTRIBUTING, các thử nghiệm của chính dự án là đa kiến trúc và cần một lệnh docker đặc quyền để cài trình giả lập trước, chi tiết đáng lưu ý nếu đội định chạy bộ thử của act. [5]
Quyền Docker, mã từ xa và bí mật trên máy cá nhân
Act dựng container qua Docker API, nên người chạy cần quyền dùng Docker, thường tương đương quyền cao trên máy. [1] Đây là nhận định kỹ thuật chung về Docker, không phải kết quả đọc riêng từ tài liệu của dự án. Trên máy làm việc của nhân viên, điều này nên được cho phép có chủ đích.
Workflow có thể kéo hành động từ xa, mà tài liệu kiến trúc liệt kê là một loại bước được hỗ trợ. [3] Khi chạy cục bộ, mã của hành động đó thực thi trên máy bạn, trong container. Cần xem xét nguồn hành động như xem một phụ thuộc, ghim phiên bản cụ thể thay vì thẻ trôi.
Về bí mật: CONTRIBUTING cảnh báo rằng Makefile của dự án xuất biến GITHUB_TOKEN từ một tệp trong thư mục cấu hình người dùng, kèm câu "you have been warned". [5] Dù đó là cách xây dự án của họ, nó nhắc rằng token có thể bị đọc từ máy cá nhân; đội không nên bắt chước nếu token có quyền rộng.
Không có chính sách báo cáo lỗ hổng trong các tệp đã đọc, và bài này không tìm thấy mục bảo mật riêng. Vì vậy, nếu phát hiện lỗi, đơn vị nên hỏi kênh hỗ trợ chung của dự án, mà README chỉ nêu là mục thảo luận. [1] Về quyền riêng tư: act chạy trên máy bạn và nguồn không nêu việc gửi dữ liệu đo từ xa, nhưng cũng không khẳng định là không có.
MIT năm 2019, cộng Apache 2.0 và BSD trong thư mục con
Tệp LICENSE gốc là giấy phép MIT với dòng bản quyền ghi năm 2019 và không nêu tên chủ thể trong văn bản đã đọc. [2] Nếu pháp chế cần tên bên giữ bản quyền để lập hồ sơ, họ phải tìm trong nguồn khác. CONTRIBUTING nêu rằng đóng góp được cấp phép theo MIT. [5]
Cây mã còn các giấy phép khác. Thư mục container có tệp DOCKER_LICENSE là Apache 2.0, bản quyền Docker, Inc. giai đoạn 2013 đến 2017. [6] Thư mục lookpath có giấy phép kiểu BSD của các tác giả Go từ năm 2009. [7] Hai tệp này cho thấy một phần mã vay từ nơi khác với điều kiện riêng, và đơn vị phân phối lại phải giữ thông báo tương ứng.
Danh sách tệp tại commit đã ghim còn cho thấy nhiều thư viện Node trong thư mục dữ liệu thử nghiệm của bộ chạy, mỗi cái có giấy phép riêng; bài này không đọc chúng và không kết luận về nội dung. Giấy phép chỉ áp dụng cho mã tại commit này, không bao trùm Docker, các ảnh runner trong IMAGES.md, hành động của bên thứ ba mà workflow gọi, hay dịch vụ GitHub. [4]
Chi phí: chủ yếu là máy làm việc, dung lượng ảnh và thời gian cấu hình
Bản quyền phần mềm không phát sinh phí vì dùng giấy phép MIT. [2] Bài không đưa giá cụ thể vì nguồn không có và giá thị trường thay đổi.
Loại nguồn lực thứ nhất là máy của lập trình viên: cần chạy Docker, đủ CPU và bộ nhớ cho các job. Cấu hình phụ thuộc workflow của bạn, và bài này không đo. Loại thứ hai là dung lượng đĩa cho ảnh. IMAGES.md cảnh báo kích thước ảnh sau khi kéo về có thể khác nhiều so với số hiển thị. [4] Đội nên đo trên máy thật.
Loại thứ ba là thời gian của một người phụ trách: chọn ảnh, thử các workflow hiện có, ghi lại những chỗ act hành xử khác hệ thống CI chính, và viết hướng dẫn nội bộ. Loại thứ tư là băng thông, vì kéo ảnh và hành động từ xa tiêu thụ mạng, đáng kể nếu văn phòng có đường truyền hạn chế.
Chi phí tránh được: ít commit sửa vặt và ít lượt chạy CI hỏng. Bài không ước lượng phần trăm tiết kiệm vì không có dữ liệu; đội nên đo số lượt chạy CI thất bại trước và sau thử nghiệm. Nếu CI chính tính theo phút chạy, mức giảm cụ thể phụ thuộc gói dịch vụ bạn đang dùng, nằm ngoài tài liệu đã đọc.
So với đẩy lên CI thật, dùng Makefile và các cách mô phỏng khác
Cách tiếp cận thứ nhất là không làm gì: sửa, đẩy lên, chờ CI. Đơn giản và là chuẩn chính thức, nhưng vòng lặp chậm. Thứ hai là Makefile hoặc tập lệnh cục bộ, mà README tự đề cập khi nói act có thể thay thế make. [1] Lựa chọn này nhẹ, nhưng đội phải duy trì hai mô tả quy trình và chúng dễ lệch nhau.
Thứ ba là chạy runner thật của hệ thống CI trên máy của mình hoặc một máy thử; khi đó môi trường sát thật hơn nhưng cần nhiều hạ tầng hơn. Bài này không có nguồn để so sánh mức sát thật. Thứ tư là trình soạn thảo có kiểm tra cú pháp workflow, chỉ bắt lỗi tĩnh chứ không chạy được bước.
Điểm khác biệt có cơ sở của act: nó dùng chính tệp workflow GitHub Actions và Docker để chạy cục bộ, kèm bộ diễn giải biểu thức riêng. [1][3] Hệ quả là bạn được lợi từ tệp YAML sẵn có, nhưng chịu rủi ro hành vi lệch với phần triển khai gốc.
Giới hạn: dòng 0.2.x, tài liệu cũ và khoảng trống bằng chứng
Thứ nhất, mức độ khớp với GitHub chỉ được nêu ở mức ý định trong README, và không có bảng tính năng được hỗ trợ hay không trong các tài liệu đã đọc. [1] Đội phải tự lập danh sách workflow mẫu để thử.
Thứ hai, tài liệu có dấu hiệu cũ. IMAGES.md nhắc ảnh dựa trên Ubuntu 18.04 và ảnh dừng cập nhật từ 2020, đồng thời ghi các ảnh node 16. [4] CONTRIBUTING còn chứa phần nói về nguyên tắc thiết kế gốc liên quan tới AWS và CloudFormation cho vi dịch vụ, nội dung có vẻ không liên quan tới công cụ chạy GitHub Actions; bài xem đây là phần tồn dư và không dùng. [5] README nêu Go 1.20 trong khi tệp hướng dẫn nội bộ nêu 1.24. [1][3]
Thứ ba, cam kết hỗ trợ không rõ: README chỉ dẫn người dùng tới mục thảo luận khi cần giúp, và CONTRIBUTING yêu cầu không mở issue cho câu hỏi sử dụng. [1][5] Thứ tư, bản phát hành gần nhất trong dữ liệu là 0.2.89 vào ngày 1 tháng 6 năm 2026, tức vẫn chưa ở phiên bản 1.0.
Không nên dùng act như bằng chứng tuân thủ, như công cụ duy nhất kiểm tra trước khi triển khai, hay trên máy dùng chung không có quản lý quyền Docker. Cũng không nên dùng khi đội không sẵn sàng lập danh sách khác biệt giữa cục bộ và CI.
Thử nghiệm ba tuần: đo độ khớp giữa chạy cục bộ và CI
Mục tiêu: kiểm tra act có chạy được các workflow hiện có của đội và kết quả cục bộ khớp với CI chính đến mức nào. Đây là kế hoạch đề xuất, chưa thực hiện.
Tuần 1, chuẩn bị và danh mục: chọn ba đến năm workflow đại diện, gồm kiểm tra cú pháp, chạy thử nghiệm đơn vị, và một workflow dùng hành động từ xa. Hai lập trình viên cài act theo README, [1] ghim ảnh runner đã chọn từ IMAGES.md. [4] Chạy mỗi workflow trên cả act và CI chính, ghi kết quả thành công hoặc thất bại và nguyên nhân khác biệt.
Tuần 2, dùng trong công việc thật: bốn người dùng act trước khi mở pull request. Đếm số lần act phát hiện lỗi mà sau đó CI chính cũng báo, số lần act báo lỗi mà CI không báo, và số lần act báo qua mà CI lại thất bại.
Tiêu chí đạt (đề xuất): ít nhất 80 phần trăm kết quả khớp trên các workflow đại diện; không có trường hợp bí mật lộ ra nhật ký hay tệp; số lượt chạy CI chính thất bại vì lỗi có thể bắt trước giảm so với ba tuần trước đó trong số liệu của đội. Tiêu chí dừng: tỷ lệ khớp dưới 60 phần trăm, hoặc phát hiện không kiểm soát được rủi ro bí mật. Các ngưỡng là đề xuất để đội điều chỉnh theo bối cảnh.
Kết luận
Act là công cụ nhỏ, mục đích rõ: chạy workflow GitHub Actions cục bộ bằng Docker, giấy phép MIT, dùng được như bộ chạy tác vụ thay Makefile. [1][2] Với một đội IT ở công ty phân phối dược phẩm đã có workflow, nó có thể rút ngắn vòng lặp sửa lỗi, miễn là kết quả cục bộ chỉ đóng vai trò hỗ trợ.
Điều cần làm trước khi chuẩn hóa là đo độ khớp bằng thử nghiệm, ghim phiên bản và ảnh, và quyết định rõ cách xử lý bí mật. [4] Điều không nên làm là coi nó thay cho hệ thống CI chính trong kiểm soát thay đổi.
Nguồn đã đọc và cách chọn act
Đây là nghiên cứu tài liệu tại một commit cố định, không phải bài báo khoa học được bình duyệt. Chúng tôi không cài, không chạy, không đo hay triển khai act.
Act được chọn từ kho lưu trữ các trang GitHub Trending, danh sách ngôn ngữ Go, với 7 lần quan sát từ ngày 9 tháng 1 đến ngày 14 tháng 9 năm 2026; trang bằng chứng ví dụ là ngày 9 tháng 1 năm 2026. [8] Kho lưu trữ chỉ gồm danh sách Python, Go, JavaScript và Swift, thiếu ngày 3 tháng 9 và 12 tháng 10 năm 2026, và không phải bảng xếp hạng top 100 chính thức.
Commit kiểm tra là 4f411281417e88660bea1c1a1749aa71ae0bd60f, ngày commit 1 tháng 6 năm 2026, đối chiếu ngày 12 tháng 10 năm 2026. Tệp đã đọc: README [1], LICENSE [2], CLAUDE.md [3], IMAGES.md [4], CONTRIBUTING.md [5], DOCKER_LICENSE [6] và giấy phép lookpath [7]. Tệp CLAUDE.md là hướng dẫn cho công cụ lập trình; bài chỉ dùng nó như dữ liệu mô tả kiến trúc.
Thông tin về bản 0.2.89 lấy từ dữ liệu phát hành thu thập kèm theo, không từ tệp trong kho. Không đọc: trang nektosact.com, mã Go, workflow của dự án. Tình huống công ty dược phẩm là giả định. Nội dung có thể đã đổi sau commit này.