Việc sử dụng Self-hosted Runner (máy chủ tự quản lý) trong GitHub Actions cho phép bạn chạy các workflow trên hạ tầng riêng của mình. Điều này hữu ích khi cần truy cập vào mạng nội bộ, xử lý dữ liệu nhạy cảm hoặc tận dụng tài nguyên phần cứng cụ thể mà không phụ thuộc vào máy chủ ảo của GitHub.

Các bước đăng ký Runner mới

1. Truy cập trang Settings của repository trên GitHub.
2. Chọn mục Actions > Runners.
3. Nhấn nút New self-hosted runner.
4. Lựa chọn hệ điều hành và kiến trúc phù hợp với server đích để lấy các lệnh cài đặt tương ứng.

Chi tiết quá trình cài đặt và cấu hình

Dưới đây là quy trình thực hiện trên môi trường Linux (x64), bao gồm việc tải package, giải nén và khởi tạo kết nối với GitHub API.

1. Tải và giải nén package Runner

Tạo thư mục làm việc, tải bản release mới nhất và kiểm tra tính toàn vẹn của file trước khi giải nén:

# Tạo thư mục chứa runner
mkdir ~/gh-runner && cd ~/gh-runner

# Tải package runner (phiên bản ví dụ: v2.319.1)
curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-linux-x64-2.319.1.tar.gz

# Kiểm tra checksum (tùy chọn nhưng khuyến nghị)
echo "3f6efb7488a183e291fc2c62876e14c9ee732864173734facc85a1bfb1744464  actions-runner-linux-x64.tar.gz" | shasum -a 256 -c

# Giải nén installer
tar xzf ./actions-runner-linux-x64.tar.gz

2. Cấu hình kết nối với Repository

Sau khi giải nén, bạn cần chạy script cấu hình để đăng ký runner với GitHub. Lệnh này yêu cầu URL của repository và một token tạm thời (ephemeral token) được cung cấp bởi giao diện web.

Ví dụ lệnh cấu hình chuẩn (khuyến nghị dùng user thường):

# Chạy script cấu hình
./config.sh --url https://github.com// --token 

Trong quá trình chạy script, hệ thống sẽ hỏi các thông tin sau:

• Runner Group Name: Nhấn Enter để chọn nhóm mặc định (Default) hoặc nhập tên nhóm tùy chỉnh nếu đã tạo sẵn.
• Runner Name: Nhập tên nhận diện cho runner (ví dụ: internal-server-01). Tên này giúp phân biệt giữa nhiều runner cùng hoạt động.
• Additional Labels: Nhập các nhãn (labels) bổ sung nếu muốn route job đến những runner cụ thể dựa trên tag (ví dụ: gpu, high-memory). Nhấn Enter nếu không cần.
• Work Folder: Đường dẫn lưu trữ workspace của runner. Mặc định là _work. Bạn có thể thay đổi sang đường dẫn tuyệt đối như /var/lib/actions-runner/_work nếu cần.

Khi cấu hình thành công, output sẽ hiển thị trạng thái √ Connected to GitHub và √ Runner connection is good.

3. Khởi động Runner

Sau khi cấu hình xong, bạn cần chạy script để bắt đầu lắng nghe các job mới từ GitHub:

# Khởi động runner ở chế độ foreground (để test nhanh)
./run.sh

Để runner hoạt động bền vững như một service, bạn nên cấu hình nó chạy nền bằng systemd hoặc Docker, thay vì giữ phiên terminal mở.

Tích hợp vào Workflow YAML

Để sử dụng self-hosted runner, bạn cần chỉ định rõ trong file workflow (`.yml`). Thay vì dùng `ubuntu-latest` hay `windows-latest`, hãy dùng label `self-hosted`.

name: Deploy Application
on: [push]

jobs:
  build-and-deploy:
    runs-on: self-hosted # Chỉ định sử dụng runner tự quản lý
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Show environment info
        run: |
          echo "Running on internal infrastructure"
          whoami
          pwd

Khi push code, log của job sẽ hiển thị thông báo chờ runner nhận task:

Requested labels: self-hosted
Job defined at: your-org/your-repo/.github/workflows/deploy.yaml@refs/heads/main
Waiting for a runner to pick up this job...

Gỡ bỏ Runner

Nếu muốn ngừng hoạt động và xóa runner khỏi danh sách của GitHub, hãy chạy lệnh remove kèm theo token mới (lấy từ giao diện web hoặc dùng token cũ nếu vẫn còn hiệu lực trong thời gian ngắn).

# Xóa cấu hình runner
./config.sh remove --token 

Lưu ý rằng việc xóa runner qua lệnh này sẽ gỡ bỏ liên kết với GitHub, nhưng các file binary trong thư mục local vẫn còn. Bạn có thể xóa thủ công thư mục đó sau khi hoàn tất.