Đặt vấn đề: Tại sao nên kết hợp Gitea Actions và GitHub Container Registry?

Trong kỷ nguyên DevOps hiện đại, việc tự động hóa quy trình tích hợp và triển khai liên tục (CI/CD) đã trở thành tiêu chuẩn bắt buộc đối với mọi đội ngũ phát triển phần mềm. Gitea, với lợi thế là một Git service tự lưu trữ (self-hosted) cực kỳ nhẹ và hiệu quả, đã tích hợp thêm Gitea Actions — một giải pháp CI/CD có cú pháp tương thích mạnh mẽ với GitHub Actions. Quy trình này giúp doanh nghiệp làm chủ hoàn toàn mã nguồn trên VPS riêng nhằm tiết kiệm chi phí, đồng thời vẫn tận dụng được hạ tầng lưu trữ Docker Image mạnh mẽ, ổn định của GitHub Container Registry (GHCR).

Bài viết này sẽ hướng dẫn bạn chi tiết từ A-Z cách cấu hình Gitea Actions trên máy chủ VPS riêng, thiết lập Runner và xây dựng một pipeline tự động đóng gói (build) rồi đẩy (push) Docker Image lên GHCR một cách chuyên nghiệp.

Phần 1: Chuẩn bị môi trường hệ thống trên VPS

Trước khi bắt đầu, hãy đảm bảo hệ thống VPS của bạn đã cài đặt sẵn các thành phần cốt lõi sau:

Một máy chủ VPS chạy hệ điều hành Linux (Ubuntu 22.04 LTS hoặc mới hơn được khuyến nghị).
Docker và Docker Compose đã được cài đặt và hoạt động ổn định.
Một phiên bản Gitea (từ v1.19 trở lên) đã kích hoạt tính năng Actions trong file cấu hình app.ini.

Để kích hoạt Gitea Actions, bạn mở file cấu hình app.ini của Gitea và thêm đoạn cấu hình sau:

[actions]
ENABLED = true

Sau đó, hãy khởi động lại dịch vụ Gitea để cấu hình mới có hiệu lực.

Phần 2: Cài đặt và đăng ký Gitea Runner (act_runner)

Gitea Actions sử dụng một thành phần gọi là act_runner để tiếp nhận và thực thi các công việc (jobs). Chúng ta sẽ triển khai Runner này thông qua Docker Compose để dễ dàng quản lý.

Bước 1: Lấy Token đăng ký từ Gitea

Đăng nhập vào giao diện Gitea với quyền Quản trị viên (Admin) hoặc vào kho lưu trữ (Repository) cụ thể của bạn, điều hướng theo lộ trình sau:

Settings -> Actions -> Runners -> Create New Runner

Tại đây, bạn sẽ thấy một chuỗi ký tự gọi là Registration Token. Hãy sao chép mã này lại vì chúng ta sẽ cần nó ở bước tiếp theo.

Bước 2: Triển khai act_runner bằng Docker Compose

Tạo một thư mục mới trên VPS và tạo file docker-compose.yml với nội dung cấu hình như sau:

version: '3.8'
services:
  runner:
    image: gitea/act_runner:latest
    environment:
      - GITEA_INSTANCE_URL=[https://gitea.yourdomain.com](https://gitea.yourdomain.com)
      - GITEA_RUNNER_REGISTRATION_TOKEN=YOUR_COPIED_TOKEN
      - GITEA_RUNNER_NAME=vps-docker-runner
      - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:18-bullseye,ubuntu-22.04:docker://node:18-bullseye
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock

Lưu ý: Bạn cần thay thế [https://gitea.yourdomain.com](https://gitea.yourdomain.com) bằng URL thực tế của Gitea và điền token thích hợp vào mục GITEA_RUNNER_REGISTRATION_TOKEN. Việc gắn kết (mount) file /var/run/docker.sock cho phép runner có quyền khởi chạy các container Docker con (Docker-in-Docker) để phục vụ quá trình build image.

Chạy lệnh lệnh sau để khởi động Runner:

docker compose up -d

Kiểm tra lại trang quản trị Gitea, bạn sẽ thấy trạng thái của Runner chuyển sang màu xanh Idle/Active, sẵn sàng nhận lệnh.

Phần 3: Cấu hình mã xác thực GitHub Personal Access Token (PAT)

Để Gitea Actions có thể đẩy Docker Image lên GitHub Container Registry một cách hợp lệ, hệ thống cần được cấp quyền truy cập thông qua một mã Token bảo mật.

Truy cập tài khoản GitHub của bạn, đi tới Settings -> Developer Settings -> Personal Access Tokens -> Tokens (classic).
Chọn Generate new token (classic).
Đặt tên cho token và tích chọn quyền: write:packages, read:packages và delete:packages.
Nhấp Generate token và sao chép mã token hiển thị trên màn hình (mã này chỉ xuất hiện một lần).

Quay trở lại kho lưu trữ trên Gitea, vào phần Settings -> Actions -> Secrets, chọn Add Secret và tạo hai biến môi trường sau:

GHCR_USERNAME: Tên đăng nhập GitHub của bạn (viết thường).
GHCR_TOKEN: Chuỗi Personal Access Token vừa khởi tạo ở trên.

Phần 4: Xây dựng Pipeline CI/CD với Gitea Actions

Bây giờ là bước quan trọng nhất: Thiết lập luồng công việc tự động. Trong kho lưu trữ mã nguồn của bạn, tạo cấu trúc thư mục và file cấu hình theo đường dẫn: .gitea/workflows/build-push.yml.

Sao chép cấu hình mẫu chuẩn hóa chuẩn hóa SEO và tối ưu hiệu năng dưới đây:

name: Build and Push Docker Image to GHCR

on:
  push:
    branches:
      - main
    tags:
      - 'v*'

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout mã nguồn
        uses: actions/checkout@v3

      - name: Thiết lập Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Đăng nhập vào GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USERNAME }}
          password: ${{ secrets.GHCR_TOKEN }}

      - name: Trích xuất Metadata cho Docker
        id: meta
        uses: docker/metadata-action@v4
        with:
          images: ghcr.io/${{ secrets.GHCR_USERNAME }}/my-app
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            latest

      - name: Tiến hành Build và Push Docker Image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Giải thích các thành phần cốt lõi trong file Pipeline:

on.push: Pipeline sẽ tự động kích hoạt khi có thao tác push code lên nhánh main hoặc khi có một thẻ tag phiên bản mới (ví dụ: v1.0.0) được tạo ra.
docker/login-action: Thực hiện đăng nhập tự động vào hệ sinh thái ghcr.io bằng các thông tin bí mật (Secrets) bảo mật đã cấu hình trên Gitea.
docker/metadata-action: Tự động phân tích, gắn nhãn (tag) cho image dựa theo ngữ cảnh như tên nhánh hoặc định dạng phiên bản SemVer, giúp quản lý lịch sử image khoa học hơn.
docker/build-push-action: Đọc file Dockerfile ở gốc thư mục, đóng gói mã nguồn thành một layer hoàn chỉnh và đẩy trực tiếp lên kho lưu trữ đám mây của GitHub.

Phần 5: Kiểm tra kết quả và vận hành thực tế

Sau khi hoàn tất cấu hình, bạn hãy thực hiện một thay đổi nhỏ dưới source code, sau đó thực hiện lệnh git commit và git push lên nhánh chính (main).

Ngay lập tức, giao diện tab Actions trên Gitea sẽ hiển thị một tiến trình đang chạy. Bạn có thể nhấp vào để xem chi tiết log xử lý thời gian thực (real-time logs) của từng bước từ việc kéo code, đăng nhập cho đến tiến trình đóng gói layer của Docker.

Khi tất cả các bước hiển thị tích xanh thành công, hãy truy cập vào mục Packages trên trang cá nhân hoặc tổ chức (Organization) của bạn trên GitHub. Bạn sẽ thấy Docker Image mới đã xuất hiện tại đây, sẵn sàng để kéo (pull) về bất kỳ môi trường production nào với độ bảo mật tuyệt đối.

Lời kết

Việc tự cấu hình Gitea Actions trên VPS riêng để đẩy Docker Image lên GHCR mang lại sự cân bằng hoàn hảo giữa tính riêng tư, tiết kiệm chi phí tài nguyên máy chủ build và tận dụng được hạ tầng CDN phân phối container hàng đầu từ GitHub. Đây là một bước tiến quan trọng giúp tối ưu hóa chu trình phát triển sản phẩm của doanh nghiệp bạn. Chúc các bạn cấu hình thành công!

Hướng Dẫn Cấu Hình Gitea Actions Trên VPS: Tự Động Hóa Đóng Gói Và Đẩy Docker Image Lên GitHub Container Registry (GHCR)