Giới thiệu về Gitea act_runner

Thông thường, Gitea Runner (act_runner) được khuyến khích chạy trong môi trường Docker để đảm bảo tính cách ly. Tuy nhiên, trong một số trường hợp đặc biệt như gặp khó khăn về kết nối mạng bên trong container hoặc cần truy cập trực tiếp vào tài nguyên hệ thống, việc chạy Runner trực tiếp trên máy chủ (Host mode) là một giải pháp tối ưu. Bài viết này sẽ hướng dẫn cách thiết lập Runner thực thi các công việc (jobs) ngay trên môi trường Linux của bạn.

Bước 1: Cài đặt và đăng ký act_runner

Đầu tiên, bạn cần tải về phiên bản act_runner phù hợp với kiến trúc hệ điều hành. Sau đó, tiến hành đăng ký Runner với máy chủ Gitea của bạn. Bạn có thể lấy Registration Token trong phần cài đặt Action của Gitea (Site Administration -> Actions -> Runners).

# Tạo thư mục làm việc cho runner
mkdir -p ~/gitea-runner-service && cd ~/gitea-runner-service

# Tải xuống phiên bản act_runner (ví dụ bản v0.2.11 cho amd64)
curl -L https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64 -o act_runner

# Cấp quyền thực thi
chmod +x act_runner

# Thực hiện đăng ký runner với server
# Bạn sẽ cần nhập URL của Gitea và Token khi được hỏi
./act_runner register

Bước 2: Cấu hình Runner chạy chế độ Host

Để Runner không gọi đến Docker mà chạy trực tiếp lệnh trên Shell của máy chủ, chúng ta cần khởi tạo file cấu hình và chỉnh sửa tham số labels.

# Xuất file cấu hình mặc định
./act_runner generate-config > runner_config.yaml

Mở file runner_config.yaml bằng trình soạn thảo văn bản và tìm đến phần runner. Chỉnh sửa mục labels như sau:

runner:
  # ... các cấu hình khác ...
  labels:
    - "linux_host:host"

Việc khai báo :host sau tên nhãn (label) thông báo cho hệ thống rằng môi trường thực thi sẽ là chính hệ điều hành hiện tại thay vì một Docker Image.

Bước 3: Chuẩn bị môi trường thực thi (Node.js)

Đa số các GitHub/Gitea Actions hiện nay yêu cầu Node.js để hoạt động. Vì chạy ở chế độ Host, bạn phải tự cài đặt Node.js trên máy chủ. Sử dụng NVM (Node Version Manager) là cách linh hoạt nhất.

# Cài đặt NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Tải cấu hình nvm vào shell hiện tại
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Cài đặt phiên bản Node.js LTS
nvm install 20
node -v # Kiểm tra phiên bản

Bước 4: Kiểm tra hoạt động với Workflow

Bây giờ, hãy khởi động Runner ở chế độ daemon:

./act_runner daemon --config runner_config.yaml

Tiếp theo, tạo một file định nghĩa quy trình tại đường dẫn .gitea/workflows/test_host.yaml trong kho mã nguồn của bạn:

name: Host Execution Demo
on: [push]

jobs:
  system-check:
    # Sử dụng label đã định nghĩa trong config.yaml
    runs-on: linux_host
    steps:
      - name: Tiếp nhận mã nguồn
        uses: actions/checkout@v4
      
      - name: Kiểm tra thông tin môi trường
        run: |
          echo "Đang chạy trên người dùng: $(whoami)"
          echo "Thư mục làm việc: $(pwd)"
          node -v
          
      - name: Liệt kê tệp tin
        run: ls -la

Xử lý vấn đề kết nối khi tải Actions

Nếu máy chủ của bạn gặp khó khăn khi kết nối tới GitHub để tải các Action (như actions/checkout), có hai cách giải quyết:

1. Sử dụng Proxy cho Git: Cấu hình trực tiếp proxy cho git trên máy chủ chạy runner:

git config --global http.proxy http://địa-chỉ-proxy:cổng
git config --global https.proxy http://địa-chỉ-proxy:cổng

2. Mirror Action về Gitea nội bộ: Bạn có thể fork hoặc mirror các repository action từ GitHub về chính server Gitea của mình và gọi chúng theo đường dẫn nội bộ trong file YAML:

- name: Checkout nội bộ
  uses: http://gitea.local/actions/checkout@v4

Lưu ý: Để quản lý tốt các action này, bạn nên chuyển các repository mirrored vào một Organization có tên là actions trên Gitea.