Hướng Dẫn Cài Đặt Gitea + Action Runner Trên Localhost

Nếu bạn cảm thấy mệt mỏi với việc phải đấu tranh với các pipeline CI/CD từ xa và muốn kiểm soát hoàn toàn quy trình làm việc của Gitea trên máy tính cá nhân, việc thiết lập một phiên bản Gitea với Action Runner trên localhost là giải pháp tuyệt vời. Thiết lập này cho phép bạn:

• Kiểm tra quy trình làm việc mà không cần đẩy lên máy chủ từ xa.
• Xây dựng và đẩy hình ảnh Docker bằng Buildx trực tiếp từ máy của bạn.
• Giữ tất cả cấu hình môi trường được phiên bản hóa và di động.

Trong hướng dẫn này, chúng ta sẽ đi từng bước, từ việc thiết lập file đến việc chạy quy trình làm việc đầu tiên của bạn.

Tại Sao Nên Sử Dụng Gitea + Runner Trên Local?

Bạn có thể tự hỏi: "Tại sao không chỉ sử dụng GitHub Actions hoặc GitLab CI?"

Dưới đây là lý do:

1. Độ trễ và kiểm soát – Các runner cục bộ phản hồi ngay lập tức, không cần chờ đợi các tác nhân từ xa.
2. Môi trường riêng tư – Không cần công khai mã nguồn hoặc bí mật của bạn lên đám mây.
3. Mạng tùy chỉnh – Bạn có thể kiểm tra các dịch vụ localhost, webhook, và thiết lập Buildx mà không cần VPN hoặc đường hầm.

Điều này đặc biệt hữu ích nếu bạn đang thử nghiệm với các registry Docker tự lưu trữ, microservices, hoặc các bản dựng đa nền tảng.

Cài Đặt Các Tệp

Chúng ta sẽ cần một vài tệp để cấu hình mọi thứ:

1. ./token.txt

Đây là token đăng ký cho runner. Tạo nó trước; tệp này sẽ trống ban đầu:

<registration-token>

Sau này, bạn sẽ dán token được cung cấp bởi phiên bản Gitea của bạn vào đây. Cách tiếp cận này giúp tránh việc Docker tạo một thư mục thay vì một tệp.

2. ./config.yml

Runner cần kết nối với phiên bản Gitea trên localhost của bạn, vì vậy chúng ta sẽ cấu hình nó để sử dụng mạng của máy chủ:

container:
  network: host

Điều này rất quan trọng cho những quy trình làm việc tương tác với các dịch vụ trên máy chủ của bạn, như các registry Docker hoặc API.

3. ./docker.compose.yml

Dưới đây là cấu hình Docker Compose cho Gitea và Action Runner:

networks:
  gitea-network:
    external: false

services:
  gitea:
    image: gitea/gitea:1.24.6
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./data/gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 3000:3000
    networks:
      - gitea-network

  gitea-runner:
    image: gitea/act_runner:0.2.13
    container_name: gitea-runner
    depends_on:
      - gitea
    networks:
      - gitea-network
    volumes:
      - ./token.txt:/token.txt
      - ./config.yml:/config.yml
      - ./data/act_runner:/data
      - ./data/cache:/root/.cache
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CONFIG_FILE=/config.yml
      - GITEA_INSTANCE_URL=http://gitea:3000/
      - GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/token.txt
    restart: on-failure

Tại sao mỗi volume lại quan trọng:

• token.txt – để đăng ký an toàn.
• config.yml – cấu hình mạng cục bộ.
• data/act_runner – lưu trữ dữ liệu của runner giữa các lần khởi động.
• data/cache – lưu trữ các tệp tải xuống action.
• /var/run/docker.sock – cho phép runner kiểm soát Docker trên máy chủ của bạn.

Chạy Thiết Lập

1. Khởi động mọi thứ:

docker compose up -d

2. Dán token đăng ký của runner vào ./token.txt.

3. Khởi động lại runner để đăng ký:

docker compose restart gitea-runner

Mẹo: Kiểm tra nhật ký để xác nhận việc đăng ký:

docker logs gitea-runner

Ví Dụ Về Quy Trình Làm Việc

Hãy xây dựng một hình ảnh Docker đơn giản để kiểm tra thiết lập của chúng ta.

Dockerfile

FROM busybox:1.36.1
CMD ["echo", "Hello world!"]

Quy Trình Làm Việc Gitea: ./gitea/workflows/example.yml

name: Workflow Example

on:
  - push

jobs:
  Build and push image:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup QEMU
        uses: docker/setup-qemu-action@v3

      - name: Setup Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver-opts: network=host

      - name: Login to registry
        uses: docker/login-action@v2
        with:
          registry: http://localhost:3000
          username: <username>
          password: <application-token>

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            localhost:3000/${{ gitea.repository }}:latest
            localhost:3000/${{ gitea.repository }}:${{ gitea.sha }}

Thay thế <username> và <application-token> bằng thông tin xác thực Gitea của bạn.

Bây giờ bạn đã có một môi trường Gitea + Action Runner hoàn chỉnh trên localhost. Bạn có thể:

• Kiểm tra quy trình làm việc ngay lập tức.
• Xây dựng hình ảnh Docker cục bộ bằng Buildx.
• Thử nghiệm với CI/CD tự lưu trữ mà không cần động chạm đến đám mây.

Từ đây, bạn có thể mở rộng thiết lập: thêm nhiều runner, kết nối với các registry bên ngoài, hoặc tích hợp với các dịch vụ cục bộ khác.

Hướng dẫn này được hỗ trợ bởi ChatGPT 5 Mini — trợ lý AI địa phương của bạn.