DPTCloud
Quay lại danh sách
Tin tức công nghệ

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

29 tháng 5, 2026

Giới thiệu về Gitea Actions và Xu hướng CI/CD Self-Hosted

Trong kỷ nguyên chuyển đổi số và phát triển phần mềm hiện đại, quy trình Tự động hóa tích hợp và Triển khai liên tục (CI/CD) đã trở thành một tiêu chuẩn bắt buộc đối với mọi đội ngũ công nghệ. Các dịch vụ đám mây lớn như GitHub Actions, GitLab CI/CD hay Bitbucket Pipelines mang lại sự tiện lợi vượt trội, nhưng đi kèm với đó là chi phí vận hành không hề nhỏ khi quy mô dự án và tần suất build tăng lên. Đặc biệt, đối với các doanh nghiệp vừa và nhỏ (SMEs) hoặc các nhà phát triển cá nhân, việc kiểm soát chi phí hạ tầng và bảo mật mã nguồn nội bộ là bài toán cực kỳ nan giải.

Chính vì lý do đó, xu hướng sử dụng các giải pháp Self-Hosted CI/CD ngày càng được ưa chuộng. Trong số các công cụ mã nguồn mở nổi bật hiện nay, Gitea nổi lên như một giải pháp thay thế hoàn hảo cho GitHub nhờ tính nhẹ nhẹ, hiệu năng cao và yêu cầu tài nguyên phần cứng cực kỳ thấp. Kể từ phiên bản 1.19, Gitea chính thức tích hợp Gitea Actions — một hệ thống CI/CD mạnh mẽ sử dụng cú pháp YAML tương thích gần như hoàn toàn với GitHub Actions. Bài viết này sẽ hướng dẫn bạn chi tiết cách tận dụng sức mạnh của Gitea Actions ngay trên VPS riêng để tự động đóng gói ứng dụng thành Docker Image và đẩy lên GitHub Container Registry (GHCR).

Tại sao nên kết hợp Gitea Actions với GitHub Container Registry (GHCR)?

Việc kết hợp một nền tảng quản lý mã nguồn nội bộ (Gitea) với một kho lưu trữ Image đám mây (GHCR) mang lại nhiều lợi ích chiến lược cho doanh nghiệp:

  • Tối ưu hóa tài nguyên VPS: Việc đóng gói (build) Docker Image tiêu tốn rất nhiều tài nguyên CPU và RAM. Bằng cách đẩy Image lên GHCR thay vì lưu trữ trực tiếp trên VPS, bạn giải phóng không gian ổ đĩa và băng thông cho máy chủ.
  • Tận dụng hạ tầng CDN của GitHub: GHCR cung cấp tốc độ tải (pull) và đẩy (push) cực nhanh nhờ hạ tầng toàn cầu của GitHub, giúp việc triển khai ứng dụng lên các môi trường production khác diễn ra mượt mà.
  • Cú pháp quen thuộc, dễ chuyển đổi: Gitea Actions sử dụng công cụ thực thi act_runner, cho phép bạn viết workflow bằng cú pháp YAML của GitHub Actions. Đội ngũ kỹ sư không cần mất thời gian học một công cụ mới.
  • Bảo mật thông tin tối đa: Mã nguồn và các bước kiểm thử nội bộ được thực hiện khép kín trên VPS riêng của bạn, chỉ có sản phẩm đóng gói cuối cùng mới được đưa lên registry.

Điều kiện tiên quyết trước khi cấu hình

Để thực hiện thành công bài hướng dẫn này, hệ thống của bạn cần chuẩn bị sẵn các thành phần sau:

  1. Một máy chủ ảo (VPS) đã cài đặt sẵn Gitea (phiên bản 1.19 trở lên) và có địa chỉ IP công khai hoặc domain trỏ về.
  2. Docker và Docker Compose đã được cài đặt trên VPS để chạy các container.
  3. Một tài khoản GitHub cá nhân hoặc tổ chức để truy cập và sử dụng GitHub Container Registry.
  4. Quyền quản trị viên trên Gitea để kích hoạt tính năng Actions.

Bước 1: Cấu hình và Kích hoạt Gitea Actions Runner

Mặc dù Gitea tích hợp sẵn giao diện quản lý Actions, bạn vẫn cần một thành phần gọi là act_runner để thực thi các job trong workflow. Thành phần này hoạt động như một agent độc lập nhận lệnh từ Gitea Server.

1.1. Lấy Token Đăng Ký từ Gitea

Đầu tiên, bạn đăng nhập vào giao diện Gitea với quyền quản trị viên. Truy cập vào mục Site Administration (Quản trị hệ thống) > Actions > Runners. Nhấp vào nút Create New Runner và sao chép chuỗi mã Registration Token được hiển thị trên màn hình. Chuỗi token này rất quan trọng để xác thực runner với hệ thống của bạn.

1.2. Triển khai act_runner bằng Docker Compose

Trên VPS của bạn, tạo một thư mục mới và cấu hình file docker-compose.yml để khởi chạy runner:

Lưu ý: Hãy thay thế URL của Gitea Server và Token đăng ký của bạn vào các biến môi trường tương ứng dưới đây.

version: "3.8"
services:
  runner:
    image: gitea/act_runner:latest
    environment:
      - GITEA_INSTANCE_URL=https://git.yourdomain.com
      - GITEA_RUNNER_REGISTRATION_TOKEN=YOUR_SECRET_REGISTRATION_TOKEN
      - GITEA_RUNNER_NAME=vps-internal-runner
      - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always

Chạy lệnh docker compose up -d để khởi động runner. Quay lại giao diện Gitea, bạn sẽ thấy trạng thái của runner chuyển sang màu xanh Idle, sẵn sàng tiếp nhận các tác vụ build.

Bước 2: Tạo GitHub Personal Access Token (PAT) để xác thực GHCR

Để Gitea Actions từ VPS của bạn có thể đẩy Docker Image lên GitHub Container Registry, bạn cần cấp quyền truy cập thông qua một mã thông báo bảo mật (PAT).

  1. Truy cập vào tài khoản GitHub của bạn, đi đến Settings > Developer Settings > Personal Access Tokens > Tokens (classic).
  2. Chọn Generate new token (classic).
  3. Đặt tên cho token (ví dụ: gitea-vps-ghcr-token) và thiết lập thời gian hết hạn phù hợp.
  4. Chọn các quyền (scopes) bắt buộc sau đây:
    • write:packages — Cho phép đẩy Docker Image lên kho chứa.
    • read:packages — Cho phép tải Docker Image về (nếu cần).
  5. Nhấn Generate token và sao chép mã token xuất hiện. Hãy lưu trữ cẩn thận vì bạn sẽ không thể xem lại mã này lần thứ hai.

Bước 3: Cấu hình Secrets trên Gitea Repository

Để đảm bảo an toàn thông tin, chúng ta không được phép ghi trực tiếp tài khoản và PAT của GitHub vào file cấu hình YAML công khai. Gitea cung cấp tính năng mã hóa Secrets tương tự như GitHub.

Vào repository của bạn trên Gitea, chọn Settings > Actions > Secrets. Tiến hành thêm hai biến môi trường sau:

  • GHCR_USERNAME: Tên đăng nhập (username) tài khoản GitHub của bạn.
  • GHCR_TOKEN: Mã Personal Access Token (PAT) vừa khởi tạo ở Bước 2.

Bước 4: Viết File Cấu Hình Workflow CI/CD

Bây giờ là bước quan trọng nhất: định nghĩa quy trình tự động hóa. Trong thư mục gốc của dự án trên Gitea, bạn tạo cấu trúc thư mục sau: .gitea/workflows/ và tạo một file có tên build-push-ghcr.yml.

Dưới đây là nội dung file cấu hình hoàn chỉnh sử dụng các Action tiêu chuẩn:

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 Source Code
        uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ secrets.GHCR_USERNAME }}
          password: ${{ secrets.GHCR_TOKEN }}

      - name: Extract Metadata for 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: Build and Push Docker Image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Phân tích các thành phần cốt lõi trong Workflow

Để giúp bạn làm chủ hoàn toàn quy trình này, hãy cùng phân tích sâu vào các bước xử lý của đoạn mã YAML trên:

  • Sự kiện kích hoạt (on): Workflow được cấu hình để tự động chạy bất cứ khi nào có hành động push code lên nhánh main hoặc khi bạn tạo một bản phát hành mới với tag định dạng dạng mã phiên bản (ví dụ: v1.0.0).
  • docker/login-action: Bước này thực hiện đăng nhập vào hệ thống của GitHub Container Registry (ghcr.io) bằng cách sử dụng các thông tin bảo mật mã hóa (Secrets) mà chúng ta đã cấu hình ở bước 3.
  • docker/metadata-action: Đây là một công cụ tuyệt vời giúp tự động gắn nhãn (tag) cho Docker Image. Nếu push lên nhánh main, image sẽ có tag là main và latest. Nếu push tag phiên bản, image sẽ tự động lấy đúng số phiên bản đó làm tag trên registry.
  • Bộ nhớ đệm (Cache-from/Cache-to): Sử dụng type=gha cho phép tận dụng tính năng caching của Gitea Actions. Các layer của Docker Image không thay đổi sẽ không phải build lại từ đầu, giúp tăng tốc độ xử lý lên đến 80% trong các lần build tiếp theo.

Bước 5: Thử nghiệm và Kiểm tra kết quả

Sau khi hoàn tất việc tạo file cấu hình, hãy thực hiện lệnh git add, git commit và git push toàn bộ mã nguồn lên Gitea Server.

Ngay lập tức, bạn truy cập vào tab Actions trên giao diện web của Gitea. Bạn sẽ thấy một workflow mới đang được kích hoạt và chuyển sang trạng thái Running. Nhấp vào chi tiết workflow để xem log trực tiếp từ VPS gửi về. Quá trình tải mã nguồn, cài đặt môi trường buildx, đăng nhập GHCR và build Docker Image sẽ được hiển thị chi tiết theo thời gian thực.

Khi tất cả các bước đều hiển thị tích xanh thành công, bạn hãy đăng nhập vào tài khoản GitHub của mình, truy cập mục Packages. Tại đây, bạn sẽ thấy Docker Image mới của ứng dụng đã xuất hiện an toàn và sẵn sàng để sử dụng cho việc triển khai (deploy) ở bất cứ hệ thống nào.

Kết luận và Khuyến nghị bảo mật

Việc xây dựng một hệ thống CI/CD khép kín kết hợp giữa Gitea Actions chạy trên VPS và GitHub Container Registry là một giải pháp kiến trúc phần mềm thông minh, dung hòa tốt giữa yếu tố chi phí, tính độc lập công nghệ và hiệu năng vận hành. Hệ thống này giúp các lập trình viên tập trung hoàn toàn vào việc viết code mà không phải lo lắng về các thao tác thủ công rườm rà.

Để hệ thống vận hành an toàn trong môi trường production, doanh nghiệp cần lưu ý một số khuyến nghị bảo mật quan trọng sau: Luôn định kỳ kiểm tra và thu hồi các Personal Access Token (PAT) không còn sử dụng; giới hạn quyền hạn của VPS runner ở mức tối thiểu cần thiết; và cấu hình dọn dẹp các Docker layer cũ (Garbage Collection) trên VPS để tránh tình trạng đầy ổ cứng. Chúc các bạn cấu hình thành công!

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