Blog

Cách Chạy GitHub Actions Của Bạn Một Cách Cục Bộ Với Act

中村 拓也

中村 拓也

16 tháng 4 2025

Cách Chạy GitHub Actions Của Bạn Một Cách Cục Bộ Với Act

Các hành động trên GitHub đã cách mạng hóa cách mà các nhà phát triển tự động hóa quy trình làm việc trong các kho chứa của họ. Từ việc tích hợp liên tục và triển khai liên tục (CI/CD) đến việc tự động gán nhãn vấn đề và tạo ghi chú phát hành, các hành động cung cấp một cách mạnh mẽ, tích hợp để quản lý vòng đời phát triển phần mềm ngay bên trong GitHub.

Tuy nhiên, việc phát triển và thử nghiệm các quy trình làm việc này đôi khi có thể cảm thấy c cumbersome. Vòng đời truyền thống bao gồm:

  1. Thay đổi các tệp quy trình làm việc của bạn (thường nằm trong .github/workflows/).
  2. Cam kết các thay đổi này.
  3. Đẩy chúng lên kho chứa GitHub của bạn.
  4. Chờ đợi các runner của GitHub lấy công việc và thực thi nó.
  5. Phân tích các nhật ký trên trang web GitHub để xem liệu các thay đổi của bạn có hoạt động hay không, hoặc nếu chúng gây ra lỗi.

Quá trình này, đặc biệt là phần chờ đợi và việc chuyển đổi giữa trình soạn thảo địa phương của bạn và giao diện người dùng của GitHub, có thể làm chậm đáng kể sự phát triển, đặc biệt là khi lặp lại trên các quy trình làm việc phức tạp hoặc gỡ lỗi các vấn đề khó khăn. Nếu bạn có thể thử nghiệm các hành động của mình trước khi đẩy chúng lên, thì sao?

Đúng ở chỗ này, act xuất hiện. Như khẩu hiệu của nó gợi ý, "Hãy nghĩ toàn cầu, act địa phương". act là một công cụ dòng lệnh mã nguồn mở được thiết kế để chạy các quy trình làm việc của GitHub Actions ở chế độ địa phương bằng cách sử dụng các container Docker. Nó mô phỏng môi trường mà GitHub Actions cung cấp, giúp bạn thử nghiệm và lặp lại trên các quy trình làm việc của mình một cách nhanh chóng mà không cần cam kết và đẩy mỗi thay đổi nhỏ.

💡
Bạn có muốn một công cụ Kiểm tra API tuyệt vời được tạo ra tài liệu API đẹp mắt?

Bạn có muốn một nền tảng tích hợp, Tất cả trong một cho Nhóm Phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng tất cả các yêu cầu của bạn, và thay thế Postman với giá cả phải chăng hơn nhiều!
button

Tại sao phải chạy GitHub Actions ở chế độ cục bộ với act?

Các lợi ích của việc tích hợp act vào quy trình phát triển của bạn là rất lớn:

  1. Phản hồi nhanh: Đây là lợi thế chính. Thay vì vòng hợp nhất-đẩy-chờ-gỡ lỗi, bạn có thể chạy quy trình làm việc ngay sau khi thực hiện thay đổi tại địa phương. Nhận phản hồi trong vài giây hoặc vài phút, không phải trong vài phút hoặc hàng chục phút. Điều này làm tăng tốc độ phát triển và quy trình gỡ lỗi cho các tệp .github/workflows/ của bạn một cách đáng kể.
  2. Trình chạy tác vụ cục bộ: Nhiều dự án sử dụng các công cụ như make, npm scripts, hoặc các script shell tùy chỉnh để định nghĩa các tác vụ phát triển chung (biên dịch, thử nghiệm, kiểm tra mã, v.v.). act cho phép bạn hợp nhất các tác vụ này. Bạn có thể định nghĩa quy trình xây dựng, kiểm tra và các quy trình khác dưới dạng công việc của GitHub Actions, và sau đó sử dụng act để chạy các công việc mà bạn đã định nghĩa trước đó tại địa phương cho các mục đích phát triển. Điều này giảm thiểu sự trùng lặp và đảm bảo tính nhất quán giữa môi trường phát triển địa phương của bạn và quy trình CI/CD của bạn. Bạn định nghĩa các tác vụ một lần trong các tệp quy trình làm việc của bạn, và chúng sẽ chạy giống hệt (hoặc rất giống) ở mọi nơi.
  3. Phát triển ngoại tuyến: Kiểm tra cú pháp và logic của quy trình làm việc cơ bản ngay cả khi không có kết nối internet liên tục (dù việc tải xuống hình ảnh ban đầu và một số hành động có thể cần kết nối).
  4. Tiết kiệm chi phí: Mặc dù GitHub cung cấp một mức miễn phí hào phóng cho các kho công khai và giá cả hợp lý cho các kho riêng tư, việc chạy các quy trình làm việc phức tạp hoặc dài trong thời gian phát triển có thể tiêu tốn rất nhiều phút chạy. Thử nghiệm tại địa phương giúp tránh việc sử dụng này.
  5. Sức mạnh gỡ lỗi: Gỡ lỗi các hành động thất bại trên GitHub thường liên quan đến việc thêm nhật ký bổ sung, đẩy và chờ đợi. Với act, bạn có thể kiểm tra môi trường địa phương, gắn các volume, và có khả năng sử dụng các kỹ thuật gỡ lỗi nâng cao hơn trong các container Docker mà nó khởi động.

act hoạt động như thế nào?

Hiểu cơ chế phía sau act giúp sử dụng nó hiệu quả và khắc phục các vấn đề tiềm năng. Dưới đây là một phân tích về cách thức hoạt động của nó:

  1. Phân tích quy trình làm việc: Khi bạn thực thi lệnh act trong thư mục gốc của kho chứa của bạn, nó quét thư mục .github/workflows/ để tìm các tệp YAML quy trình làm việc của bạn.
  2. Mô phỏng kích hoạt sự kiện: Theo mặc định, act mô phỏng một sự kiện push, nhưng bạn có thể chỉ định các sự kiện khác như pull_request, workflow_dispatch, v.v. Nó xác định các quy trình làm việc và công việc nào nên chạy dựa trên sự kiện được chỉ định và các kích hoạt on: được định nghĩa trong các tệp quy trình làm việc của bạn.
  3. Phân tích phụ thuộc: act phân tích các phụ thuộc giữa các công việc trong một quy trình làm việc (sử dụng từ khóa needs:) để xác định đúng thứ tự thực hiện.
  4. Quản lý hình ảnh Docker: Đối với mỗi công việc, act xác định môi trường trình chạy được chỉ định (ví dụ: runs-on: ubuntu-latest). Sau đó, nó ánh xạ điều này tới một hình ảnh Docker cụ thể. act sử dụng API Docker để:
  1. Thực thi container: act sử dụng API Docker để tạo và chạy các container cho mỗi bước trong một công việc. Nó cấu hình những container này để mô phỏng môi trường của GitHub Actions một cách chính xác nhất có thể:
  1. Luồng nhật ký: act phát luồng nhật ký từ các container đang chạy trực tiếp đến terminal của bạn, cung cấp phản hồi theo thời gian thực về tiến trình thực hiện và bất kỳ lỗi nào.

Về cơ bản, act tổ chức các container Docker tại địa phương để tái tạo quy trình thực thi và môi trường của các quy trình làm việc GitHub Actions của bạn.

Yêu cầu: Cài đặt Docker

Tùy thuộc chính để act là Docker. act sử dụng engine Docker để tạo ra các môi trường cách ly cần thiết để chạy các bước quy trình làm việc của bạn. Trước khi cài đặt act, bạn phải có một cài đặt Docker hoạt động trên hệ thống của bạn.

Cài đặt act

Sau khi Docker đang chạy, bạn có thể cài đặt act. Có một số cách để làm điều này, tùy thuộc vào hệ điều hành và sở thích của bạn.

1. Homebrew (macOS và Linux)

Nếu bạn sử dụng package manager Homebrew, việc cài đặt rất đơn giản:

brew install act

Điều này cài đặt phiên bản ổn định mới nhất. Nếu bạn muốn phiên bản phát triển mới nhất (có thể yêu cầu một trình biên dịch), bạn có thể sử dụng:

brew install act --HEAD

2. Mở rộng GitHub CLI (macOS, Windows, Linux)

Nếu bạn đã sử dụng GitHub CLI (gh), bạn có thể cài đặt act như một tiện ích mở rộng:

gh extension install nektos/gh-act

Sau khi cài đặt, bạn gọi act thông qua lệnh gh:

gh act          # Thay vì chỉ 'act'
gh act -l
gh act pull_request

3. Chocolatey (Windows)

Đối với người dùng của package manager Chocolatey trên Windows:

choco install act-cli

(Lưu ý: Một số nguồn có thể liệt kê act thay vì act-cli. Kiểm tra tên gói mới nhất trên kho cộng đồng Chocolatey nếu bạn gặp vấn đề.)

4. Scoop (Windows)

Đối với người dùng của package manager Scoop trên Windows:

scoop install act

5. WinGet (Windows)

Đối với người dùng của Windows Package Manager (winget):

winget install nektos.act

6. Trình cài đặt Script Linux

Có sẵn một script tiện lợi cho các bản phân phối Linux mà không dễ dàng tiếp cận qua các package manager:

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

(Lưu ý: Luôn thận trọng khi gửi các script trực tiếp vào sudo. Xem qua nội dung của script trước nếu bạn có lo ngại về bảo mật.)

7. Các phương pháp khác (Arch, COPR, MacPorts, Nix)

Các hướng dẫn cài đặt cho các package manager khác như pacman (Arch), COPR (Fedora), MacPorts và Nix có sẵn trong tài liệu chính thức của act:

Xác minh:

Sau khi cài đặt, mở một cửa sổ terminal mới và chạy:

act --version
# hoặc nếu sử dụng tiện ích mở rộng gh:
gh act --version

Điều này sẽ in ra phiên bản đã cài đặt của act, xác nhận rằng việc cài đặt thành công.

Cấu hình ban đầu: Hình ảnh trình chạy

Lần đầu tiên bạn chạy act trong một thư mục dự án, nó có thể yêu cầu bạn chọn một kích thước hình ảnh trình chạy mặc định. GitHub Actions cung cấp các trình chạy với nhiều nguồn lực và phần mềm đã được cài đặt sẵn. act cố gắng mô phỏng điều này bằng cách sử dụng các hình ảnh Docker cơ bản khác nhau.

Bạn thường được trình bày với sự lựa chọn như này:

? Vui lòng chọn hình ảnh mặc định bạn muốn sử dụng với act:

  - Micro: Hình ảnh tối thiểu với hỗ trợ nodejs (~200MB) docker.io/node:16-buster-slim
  - Medium: Hình ảnh Act với các công cụ cơ bản (~500MB) ghcr.io/catthehacker/ubuntu:act-latest
  - Large: Hình ảnh trình chạy Github Actions (~17GB) ghcr.io/catthehacker/ubuntu:full-latest

Hình ảnh mặc định? [Medium]:

Khuyến nghị: Bắt đầu với hình ảnh Medium. Nó cung cấp một sự cân bằng tốt và hoạt động cho nhiều trường hợp sử dụng phổ biến. Nếu bạn gặp các vấn đề do phần mềm thiếu, bạn có thể cài đặt phần mềm đó trong các bước quy trình làm việc của bạn hoặc chuyển sang sử dụng hình ảnh lớn cho trình chạy cụ thể đó (thông tin này sẽ được nêu sau).

act lưu lựa chọn của bạn trong một tệp cấu hình (~/.actrc). Bạn có thể thay đổi mặc định sau đó bằng cách chỉnh sửa tệp này hoặc chạy lại act trong một thư mục mà nó cần cấu hình.

Sử dụng cơ bản của act: Chạy các quy trình của bạn

Khi đã cài đặt và cấu hình, việc sử dụng act tương đối đơn giản. Điều hướng đến thư mục gốc của dự án của bạn (thư mục chứa thư mục .github) trong terminal của bạn.

1. Chạy Sự kiện Mặc định (push)

Lệnh đơn giản nhất chạy các quy trình làm việc được kích hoạt bởi sự kiện mặc định push:

act
# hoặc
gh act

act sẽ phân tích các quy trình làm việc của bạn, xác định các công việc được kích hoạt on: push, kéo các hình ảnh Docker cần thiết (nếu chưa được lưu vào cache) và thực hiện các công việc đó.

2. Danh sách Các quy trình và Công việc có sẵn

Để xem các quy trình làm việc và công việc nào mà act nhận diện và sẽ chạy cho sự kiện mặc định:

act -l
# hoặc 
gh act -l

Điều này sẽ xuất ra một danh sách như:

Stage  Job ID        Job name      Workflow name  Workflow file  Events
0      build         Build         CI Pipeline    ci.yaml        push
1      test          Test          CI Pipeline    ci.yaml        push
1      lint          Lint          Code Quality   codeql.yaml    push,pull_request

3. Chạy một Công việc Cụ thể

Nếu bạn chỉ muốn kiểm tra một công việc đơn lẻ từ một quy trình làm việc, sử dụng cờ -j theo sau là ID công việc (từ đầu ra act -l):

act -j build
# hoặc
gh act -j build

4. Kích hoạt một Sự kiện Cụ thể

Các quy trình làm việc thường được kích hoạt bởi các sự kiện khác ngoài push. Bạn có thể mô phỏng các sự kiện này bằng cách cung cấp tên sự kiện như một đối số cho act:

# Mô phỏng một sự kiện pull request
act pull_request

# Mô phỏng một sự kiện workflow_dispatch (kích hoạt thủ công)
act workflow_dispatch

# Mô phỏng một sự kiện lịch trình
act schedule

# Mô phỏng một sự kiện phát hành
act release -e event.json # Cung cấp chi tiết payload sự kiện nếu cần

act sẽ chỉ thực thi các quy trình làm việc và công việc được cấu hình để chạy on: sự kiện đã chỉ định.

5. Truyền Đầu vào cho workflow_dispatch

Các quy trình làm việc được kích hoạt bởi workflow_dispatch có thể chấp nhận đầu vào. Bạn có thể cung cấp chúng bằng cách sử dụng cờ --input hoặc -i:

# Giả sử quy trình làm việc của bạn có một đầu vào tên 'environment'
act workflow_dispatch --input environment=staging

6. Xử lý Bí mật

Các quy trình làm việc trong GitHub Actions thường phụ thuộc vào các bí mật (như khóa API hoặc token). act không tự động truy cập vào các bí mật GitHub của bạn. Bạn cần cung cấp chúng tại địa phương.

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

Hoặc, chỉ act -s sẽ yêu cầu tất cả các bí mật.

export SECRET_MY_SECRET_TOKEN="your_value"
act

MY_SECRET_TOKEN=your_value
ANOTHER_SECRET=another_value

Sau đó chạy act với cờ --secret-file:

act --secret-file .secrets

(Đảm bảo tệp này được thêm vào .gitignore để tránh cam kết các bí mật!)

7. Xử lý Các biến và Biến Môi trường

act --env NODE_ENV=development --env CUSTOM_FLAG=true
act --env-file .env_vars

Quản lý Các Môi trường và Hình ảnh Trình chạy

Khi các hình ảnh trình chạy mặc định (Micro, Medium, Large) đáp ứng nhiều kịch bản, bạn thường cần kiểm soát nhiều hơn.

1. Hạn chế của các hình ảnh mặc định

Hãy nhớ rằng các hình ảnh trình chạy act mặc định (đặc biệt là Micro và Medium) không hoàn toàn giống với các môi trường do GitHub cung cấp. Chúng có thể thiếu các công cụ, thư viện cụ thể, hoặc dịch vụ hệ thống (như systemd) mà quy trình làm việc của bạn mong đợi. Các hình ảnh lớn cung cấp độ chính xác cao hơn nhưng đi kèm với hạn chế kích thước đáng kể.

2. Chỉ định Các Hình ảnh Thay thế với -P

Nếu một công việc cần một môi trường hoặc bộ công cụ cụ thể không có trong hình ảnh mặc định, bạn có thể yêu cầu act sử dụng một hình ảnh Docker khác cho một nền tảng cụ thể bằng cách sử dụng cờ -P (nền tảng).

Định dạng là -P <nền tảng>=<docker-image>.

Ví dụ:

# Sử dụng hình ảnh lớn cụ thể cho các công việc chạy trên ubuntu-22.04
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04

# Sử dụng một phiên bản Node.js cụ thể cho các công việc ubuntu-latest
act -P ubuntu-latest=node:18-bullseye

# Sử dụng một hình ảnh đầy đủ hơn từ nektos/act-environments (rất lớn!)
# CẢNH BÁO: nektos/act-environments-ubuntu:18.04 là >18GB
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

# Chỉ định nhiều nền tảng nếu quy trình làm việc của bạn sử dụng chúng
act -P ubuntu-20.04=node:16-buster -P ubuntu-22.04=node:18-bullseye

3. Sử dụng Hình ảnh Trình chạy Tại địa phương (--pull=false)

Theo mặc định, act cố gắng kéo phiên bản mới nhất của hình ảnh Docker được chỉ định mỗi khi nó chạy. Nếu bạn đã xây dựng một hình ảnh trình chạy tùy chỉnh tại địa phương hoặc muốn đảm bảo rằng bạn đang sử dụng chính xác phiên bản mà bạn đã lưu vào cache, bạn có thể tắt hành vi này:

act --pull=false
# hoặc có thể sử dụng chế độ ngoại tuyến
act --action-offline-mode

Điều này khiến act sử dụng hình ảnh có sẵn tại địa phương nếu có và chỉ cố gắng kéo nếu nó không có.

4. Chạy Natively trên Máy chủ (-self-hosted)

Đối với các quy trình làm việc nhắm đến macOS hoặc Windows (runs-on: macos-latest hoặc runs-on: windows-latest), nếu bạn đang chạy act trên cùng hệ điều hành máy chủ đó, bạn có thể hướng dẫn act không sử dụng một container Docker cho chính trình chạy. Thay vào đó, nó sẽ thực hiện các bước trực tiếp trên máy chủ của bạn. Điều này có thể hữu ích nếu khả năng tương thích Docker là một vấn đề hoặc nếu bạn cần truy cập trực tiếp vào các tài nguyên của máy chủ.

# Chạy các công việc macos-latest trực tiếp trên máy Mac của bạn
act -P macos-latest=-self-hosted

# Chạy các công việc windows-latest trực tiếp trên máy Windows của bạn
act -P windows-latest=-self-hosted

Cảnh giác: Chạy trực tiếp trên máy chủ bỏ qua sự cách ly do Docker cung cấp. Các bước của quy trình sẽ có quyền truy cập vào hệ thống tệp của bạn và có thể thay đổi môi trường máy chủ của bạn. Sử dụng tùy chọn này với sự cẩn thận. Các bước trong công việc mà rõ ràng sử dụng các container Docker (như các container dịch vụ hoặc các hành động container) sẽ vẫn sử dụng Docker.

Hạn chế và Cân nhắc

Mặc dù act rất hữu ích, nhưng quan trọng là phải nhận thức được những hạn chế của nó:

Khuyến nghị: Sử dụng act để phát triển nhanh chóng, kiểm tra cú pháp, kiểm tra logic cơ bản và lặp lại trên các công việc hoặc bước riêng lẻ. Luôn thực hiện xác minh cuối cùng bằng cách chạy các quy trình làm việc của bạn trên chính GitHub trước khi hợp nhất các thay đổi quan trọng, đặc biệt là đối với các quy trình triển khai. Tham khảo tài liệu chính thức của act để có bảng hỗ trợ chi tiết và các vấn đề đã biết.

Kết luận

Thử nghiệm các hành động của GitHub ở chế độ cục bộ là một yếu tố tăng năng suất lớn, biến vòng lặp gỡ lỗi có thể chậm chạp và tốn thời gian thành một quy trình nhanh chóng, lặp lại. Công cụ CLI act cung cấp một cách linh hoạt và mạnh mẽ để đạt được điều này bằng cách tận dụng Docker để mô phỏng môi trường trình chạy GitHub Actions trên máy tính địa phương của bạn.

Bằng cách tích hợp act vào quy trình làm việc của bạn, bạn có được:

Mặc dù nó có những hạn chế và không phải là sự thay thế hoàn hảo 1:1 cho môi trường GitHub trực tiếp, act bao phủ một loạt trường hợp sử dụng rộng lớn và giảm đáng kể ma sát liên quan đến phát triển các quy trình làm việc GitHub Actions đáng tin cậy và hiệu quả. Cài đặt nó, thử chạy các quy trình làm việc hiện có của bạn tại địa phương, và trải nghiệm những lợi ích của việc nghĩ toàn cầu trong khi hành động địa phương.

💡
Bạn có muốn một công cụ Kiểm tra API tuyệt vời được tạo ra tài liệu API đẹp mắt?

Bạn có muốn một nền tảng tích hợp, Tất cả trong một cho Nhóm Phát triển của bạn làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng tất cả các yêu cầu của bạn, và thay thế Postman với giá cả phải chăng hơn nhiều!
button

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống