Hướng Dẫn Cấu Hình Gitea Actions Trên VPS Riêng: Đóng Gói Và Tự Động Đẩy Docker Image Lên GitHub Container Registry (GHCR)
Giới thiệu về Gitea Actions và Xu Hướng Tự Động Hóa CI/CD
Trong kỷ nguyên chuyển đổi số và phát triển phần mềm hiện đại, quy trình 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 các doanh nghiệp công nghệ. Việc tự động hóa từ khâu kiểm thử, đóng gói cho đến triển khai không chỉ giúp giảm thiểu sai sót do con người mà còn tối ưu hóa tốc độ đưa sản phẩm ra thị trường. Gitea, nền tảng quản lý mã nguồn Git gọn nhẹ và mạnh mẽ, đã ra mắt Gitea Actions — một giải pháp CI/CD tích hợp sẵn có cú pháp tương thích cao với GitHub Actions.
Đối với các doanh nghiệp muốn tự chủ về hạ tầng và bảo mật dữ liệu, việc triển khai Gitea trên máy chủ ảo riêng (VPS) kết hợp với Gitea Actions là một lựa chọn kinh tế và hiệu quả. Bài viết này sẽ hướng dẫn chi tiết cách cấu hình Gitea Actions 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à GitHub Container Registry?
Việc kết hợp một công cụ quản lý mã nguồn tự lưu trữ (Self-hosted) như Gitea với một kho lưu trữ container đám mây như GHCR mang lại nhiều lợi ích chiến lược cho doanh nghiệp:
- Tiết kiệm tài nguyên VPS: Việc lưu trữ các Docker Image có dung lượng lớn trên VPS cá nhân sẽ nhanh chóng làm cạn kiệt không gian ổ đĩa. Sử dụng GHCR giúp giảm tải lưu trữ cho hệ thống nội bộ.
- Bảo mật và phân quyền mạnh mẽ: GHCR tích hợp sâu với hệ sinh thái GitHub, cho phép quản lý quyền truy cập Docker Image chi tiết theo tổ chức hoặc cá nhân.
- Tối ưu chi phí: Gitea Actions chạy trên hạ tầng VPS của bạn hoàn toàn miễn phí, không bị giới hạn số phút build như các dịch vụ đám mây công cộng.
- Sự quen thuộc: Cú pháp YAML của Gitea Actions tương đồng với GitHub Actions, giúp đội ngũ kỹ sư không mất thời gian học lại công cụ mới.
Đ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, doanh nghiệp của bạn cần chuẩn bị sẵn hạ tầng và các tài khoản sau:
- Một máy chủ VPS (Ubuntu 22.04 trở lên) đã cài đặt sẵn Docker và Docker Compose.
- Một instance Gitea v1.19 hoặc mới hơn đang hoạt động ổn định và đã kích hoạt tính năng Actions trong file cấu hình
app.ini. - Một tài khoản GitHub cá nhân hoặc tổ chức để sử dụng GHCR.
- Một mã Personal Access Token (PAT) từ GitHub với các quyền:
write:packages,read:packages, vàdelete:packages.
Bước 1: Kích hoạt Gitea Actions trên VPS
Mặc định, Gitea Actions có thể chưa được bật. Bạn cần truy cập vào file cấu hình chính của Gitea (thường nằm tại /data/gitea/conf/app.ini trong container hoặc thư mục cài đặt gốc) và thêm vào đoạn cấu hình sau:
[actions]ENABLED = true
Sau khi sửa đổi, hãy khởi động lại dịch vụ Gitea để cấu hình mới có hiệu lực. Lúc này, trên giao diện quản trị của Gitea, bạn sẽ thấy xuất hiện thêm mục "Actions" trong phần cài đặt hệ thống và cài đặt kho lưu trữ.
---Bước 2: Cài đặt và Đăng ký Gitea Act Runner
Gitea Actions cần một thành phần gọi là Act Runner để nhận và thực thi các job CI/CD. Chúng ta sẽ tiến hành cài đặt Act Runner ngay trên VPS thông qua Docker Compose.
1. Tạo thư mục làm việc và file cấu hình
Tạo một thư mục mới trên VPS để lưu trữ cấu hình của Runner:
mkdir -p /opt/gitea-runner && cd /opt/gitea-runner
2. Lấy Token đăng ký từ Gitea
Truy cập vào Gitea với quyền Admin, đi tới Site Administration -> Actions -> Runners và nhấn Create New Runner. Sao chép chuỗi Token hiển thị trên màn hình.
3. Tạo file docker-compose.yml cho Act Runner
Tạo file docker-compose.yml với nội dung sau để khởi chạy Runner:
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=THAY_THE_TOKEN_CUA_BAN - GITEA_RUNNER_NAME=vps-internal-runner - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye volumes: - /var/run/docker.sock:/var/run/docker.sock - ./data:/data restart: always
Chạy lệnh docker compose up -d để khởi chạy container. Kiểm tra lại trong giao diện Gitea để đảm bảo trạng thái của Runner đã chuyển sang màu xanh (Idle/Online).
Bước 3: Cấu hình Secrets bảo mật trên Gitea Repository
Để quy trình CI/CD có thể đăng nhập và đẩy image lên GitHub Container Registry một cách an toàn, chúng ta không được phép ghi đè thông tin đăng nhập trực tiếp vào mã nguồn. Hãy sử dụng tính năng Secrets của Gitea.
Truy cập vào Repo của bạn trên Gitea, đi tới Settings -> Actions -> Secrets và thêm hai biến sau:
- GHCR_USERNAME: Tên đăng nhập tài khoản GitHub của bạn (hoặc tên Tổ chức/Organization).
- GHCR_TOKEN: Mã Personal Access Token (PAT) đã khởi tạo ở phần điều kiện tiên quyết.
Bước 4: Xây dựng Workflow File để tự động hóa Build và Push Docker Image
Tại thư mục gốc của dự án trên Gitea, hãy tạo cấu trúc thư mục sau: .gitea/workflows/ và tạo một file có tên release.yaml. Đây là nơi định nghĩa toàn bộ kịch bản tự động hóa.
Nội dung file cấu hình chi tiết như sau:
name: Build and Push Docker Image to GHCRon: 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: Đóng gói và Đẩy Image lên GHCR uses: docker/build-push-action@v4 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }}
Lưu ý: Hãy đảm bảo rằng trong thư mục gốc của bạn đã có sẵn một file Dockerfile hợp lệ để quy trình đóng gói có thể diễn ra suôn sẻ.
Bước 5: Kiểm tra và Vận hành Hệ thống
Sau khi đã hoàn tất các bước cấu hình, quy trình vận hành sẽ diễn ra hoàn toàn tự động theo các bước sau:
- Nhà phát triển tiến hành đẩy mã nguồn mới (Push) hoặc tạo một Tag phiên bản mới (ví dụ:
v1.0.0) lên nhánhmaincủa Gitea. - Gitea Actions ngay lập tức phát hiện sự kiện và kích hoạt Act Runner trên VPS.
- Runner tải mã nguồn xuống, khởi tạo môi trường Docker, tiến hành build ứng dụng dựa trên Dockerfile.
- Sau khi build thành công, hệ thống sử dụng Secret Token để xác thực và đẩy (Push) thành phẩm lên hệ thống lưu trữ ghcr.io.
Doanh nghiệp có thể theo dõi tiến độ thời gian thực (Real-time logs) trực tiếp từ tab Actions trong kho lưu trữ Gitea để kịp thời phát hiện lỗi nếu có.
---Kết luận và Khuyến nghị tối ưu
Việc tự cấu hình Gitea Actions trên VPS riêng để đóng gói và đẩy Docker Image lên GitHub Container Registry mang lại sự cân bằng hoàn hảo giữa tính bảo mật nội bộ và sức mạnh hạ tầng đám mây. Đây là một mô hình kiến trúc tối ưu, giúp các doanh nghiệp vừa và nhỏ (SMEs) tiết kiệm chi phí vận hành đáng kể mà vẫn sở hữu một hệ thống CI/CD chuẩn doanh nghiệp lớn.
Để hệ thống hoạt động ổn định lâu dài, doanh nghiệp cần lưu ý thêm việc thiết lập các chính sách dọn dẹp (Prune) các Docker layer cũ trên VPS định kỳ, nhằm tránh tình trạng đầy ổ cứng, đồng thời bảo mật chặt chẽ mã PAT cá nhân trên GitHub.