Triển khai Gitea + CI/CD
Quản lý mã nguồn Git tự lưu trữ và tích hợp quy trình CI/CD nhẹ nhàng.
Bối cảnh & Lý do triển khai
Quản lý script, Ansible playbook, Docker Compose file bằng cách copy thủ công qua USB/chat là thực hành nguy hiểm: không có version history, không biết ai thay đổi gì khi nào, không thể rollback khi cấu hình sai phá hỏng production. Gitea mang Git workflow chuyên nghiệp vào lab, kết hợp CI/CD tự động hóa deploy.
| Mục | Nội dung |
|---|---|
| Ứng dụng trong DN | IaC repository (Ansible/Terraform), config version control, automated deployment pipeline, code review workflow |
| Tác dụng chính | Git hosting, CI runner tự động build và push lên Harbor, deploy qua SSH sau mỗi commit, webhook integration |
| Nếu không triển khai | Config drift không kiểm soát, deploy thủ công hay sai, không có rollback khi sự cố |
| Các service phụ thuộc vào đây | Harbor Registry (push image), tất cả VM nhận deploy từ Gitea CI runner |
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| gitea (Gitea + Actions) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Máy chủ của bài — Ubuntu Server 24.04 LTS chạy Gitea 28.1.0, PostgreSQL và Gitea Runner bằng Docker Compose; web HTTPS, SSH cổng 2222. |
| node2 (Proxmox VE) | 10.11.45.211 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM240; tạo VM và đặt lịch backup VM tại đây. |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | Phân giải gitea.hoatranlabs.local về 10.11.45.40 (bản ghi tạo ở bài 12). |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấp chứng chỉ TLS cho Gitea qua ACME và gia hạn bằng step ca renew + systemd timer (bài 13). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Nhà cung cấp OIDC cho nút đăng nhập SSO của Gitea (bài 14). |
| harbor (Harbor Registry) · VM239 | 10.11.45.39 | 45 (MGMT) · node2 | Registry nhận image do pipeline Gitea Actions build và đẩy lên (bài 21). |
| mailu (Mailu Mail Server) · VM246 | 10.11.35.46 | 35 (DMZ) · node2 | Relay SMTP cổng 587 (STARTTLS) gửi thông báo email của Gitea (bài 16). |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local.
Tổng Quan
Gitea là Git hosting server nhẹ, tự triển khai, kèm Gitea Actions — pipeline CI/CD tương thích cú pháp GitHub Actions. Trong lab này Gitea đóng vai trò:
| Vai trò | Mô tả |
|---|---|
| Git Hosting | Lưu source code cấu hình, scripts, Helm charts, Ansible playbooks |
| CI/CD Engine | Gitea Actions → build Docker image → push Harbor → deploy |
| IaC Repository | Lưu Terraform, Proxmox cloud-init, PVE scripts |
| Secret Store | Gitea Secrets dùng bởi Actions runner |
| SSO via Authentik | OIDC login đồng nhất với toàn lab |
Kiến trúc triển khai:
┌─────────────────────────────────────────────────────┐
│ VM240 — gitea.hoatranlabs.local │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Gitea │ │PostgreSQL│ │ Gitea Runner │ │
│ │ :3000 │ │ :5432 │ │ (act_runner) │ │
│ └──────────┘ └──────────┘ └──────────────────┘ │
│ ↓ ↓ │
│ /data/gitea /var/run/docker.sock │
└─────────────────────────────────────────────────────┘
↓ ↓
Authentik SSO Harbor Registry
(VM234) (VM239)
Cổng mở:
| Cổng | Giao thức | Mô tả |
|---|---|---|
| 443/TCP | HTTPS | Gitea Web UI + API |
| 3000/TCP | HTTPS | Cổng nội bộ trong container Gitea (compose map 443:3000, không có HTTP redirect) |
| 2222/TCP | SSH | Git SSH clone/push (tránh conflict port 22 host) |
Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15):
| Thành phần | Phiên bản | Ghi chú |
|---|---|---|
| Ubuntu Server | 24.04.5 LTS (noble) | ISO ubuntu-24.04.5-live-server-amd64.iso; hỗ trợ chuẩn tới 04/2029 |
| Docker Engine | 29.9.1 (docker-ce 5:29.9.1-1~ubuntu.24.04~noble) | Repo chính thức download.docker.com/linux/ubuntu noble stable |
| Docker Compose plugin / Buildx | 5.6.0 / 0.38.0 | Lệnh docker compose |
| Gitea | 28.1.0 | Image gitea/gitea:28.1.0 (bản Latest, 06/10/2026), giữ nguyên bản đã ghim |
| Gitea Runner | 5.1.0 | Image gitea/runner:5.1.0 (tag có trên Docker Hub) |
| Image job của runner | docker.gitea.com/runner-images nhãn ubuntu-latest, ubuntu-24.04 | Chạy trong container, độc lập với Ubuntu của VM |
| PostgreSQL / Redis | 16 (postgres:16-alpine) / 7 (redis:7-alpine) | Chạy trong container, không cài trên host |
| step-cli | 0.31.0 | Gói step-cli_0.31.0-1_amd64.deb, lệnh thực tế step-cli (có symlink step) |
Tạo VM240 Trên PVE
Tạo VM · Cài Ubuntu Server 24.04 LTS · Chuẩn Bị Môi Trường
2.1 Tạo VM
Cách 1: Web UI Proxmox (GUI)
- VM ID:
240 - Name:
gitea - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso - Guest OS Type:
Linux, Version:6.x - 2.6 Kernel
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph(thường làvm-ceph) - Disk size:
50 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:4, Type:x86-64-v2-AES
- Memory (MiB):
4096
- Bridge:
vmbr0, VLAN Tag:45, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
qm create 240 \
--name gitea \
--memory 4096 \
--balloon 0 \
--cores 4 \
--cpu host \
--net0 virtio,bridge=vmbr0,tag=45 \
--scsi0 vm-ceph:50,discard=on,ssd=1 \
--scsihw virtio-scsi-pci \
--ide2 local:iso/ubuntu-24.04.5-live-server-amd64.iso,media=cdrom \
--boot "order=ide2;scsi0" \
--ostype l26 \
--agent enabled=1 \
--onboot 1 \
--startup order=7,up=90
create-lab-vms.sh (bài 07) thì VM240 có scsi0 = 40 GB trên SSD vm-ceph (thin provisioning) và không có đĩa dữ liệu scsi1 (xdisk = 0). Số 50 GB ở bài này là trần danh nghĩa/khuyến nghị cho môi trường thật; ước tính ở bài 07 (mục 8.6) cho thấy Gitea chỉ dùng khoảng 13 GB thật (hệ điều hành + Docker ≈ 7 GB, image Gitea/PostgreSQL/runner ≈ 5 GB, repo ≈ 1 GB). Phần dễ phình nhất là image và layer cache của runner khi build CI: dọn định kỳ theo bài 07 (mục 8.7, docker image prune -f hằng tuần) và docker builder prune -f khi df -h báo trên ~70%.
2.2 Cài Ubuntu Server 24.04 LTS
Hostname: gitea
Username: sysadmin
IP: 10.11.45.40/24
Gateway: 10.11.45.1
DNS: 10.11.45.53
Disk: toàn bộ 50 GB, ext4
Packages: OpenSSH server
ubuntu-24.04.5-live-server-amd64.iso (bản point mới nhất của dòng 24.04 trên releases.ubuntu.com, kiểm 2026-10-15; hỗ trợ chuẩn tới 04/2029). Tên card mạng trên VM q35 thường là ens18 hoặc enp6s18, kiểm bằng ip -br link; nếu cloud-init ghi netplan thì file là /etc/netplan/50-cloud-init.yaml.
2.3 Chuẩn Bị Môi Trường
Dùng repo Docker chính thức cho Ubuntu 24.04 (suite noble, dạng deb822 docker.sources + Signed-By, không dùng apt-key). Chạy bằng quyền root (sudo -i).
# Cập nhật hệ thống
# (Ubuntu 24.04: needrestart có thể hiện hộp thoại chọn dịch vụ cần khởi động lại; đặt biến này để tự xử lý)
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
# Gỡ gói Docker không chính thức nếu có (docker.io, docker-compose-v2, podman-docker... của Ubuntu)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
apt-get remove -y "$pkg" 2>/dev/null || true
done
# Cài Docker CE từ repo chính thức (suite noble)
apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
tee /etc/apt/sources.list.d/docker.sources > /dev/null << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# qemu-guest-agent
apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
# Xác nhận (kiểm 2026-10-15 trên repo noble: docker-ce 29.9.1, Compose plugin 5.6.0, Buildx 0.38.0)
docker --version && docker compose version
Suites: được shell thay bằng noble nhờ heredoc không đặt nháy (<< EOF); mở /etc/apt/sources.list.d/docker.sources kiểm tra lại trước khi apt update. Docker chỉ hỗ trợ iptables-nft/iptables-legacy, và cổng container đã publish (443, 2222) có thể đi vòng qua luật ufw, nên lọc truy cập ở FortiGate (mục 10.2) thay vì chỉ dựa vào ufw. Runner mount docker.sock của Docker rootful nên các giới hạn user namespace không đặc quyền của AppArmor trên 24.04 (ảnh hưởng container rootless) không áp dụng ở đây.
Cấu Hình TLS Từ step-CA (VM242)
Tự Động Gia Hạn Cert
# Cài step CLI 0.31.0 (gói .deb của Smallstep)
wget https://github.com/smallstep/cli/releases/download/v0.31.0/step-cli_0.31.0-1_amd64.deb
apt install -y ./step-cli_0.31.0-1_amd64.deb
rm -f step-cli_0.31.0-1_amd64.deb
# Gói .deb 0.31.0 chỉ cài /usr/bin/step-cli (đã kiểm nội dung gói); tạo lệnh `step` để mọi lệnh bên dưới và service gia hạn (/usr/local/bin/step) chạy như cũ
ln -sf /usr/bin/step-cli /usr/local/bin/step
step version
# Bootstrap step-CA trust
step ca bootstrap \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--fingerprint <fingerprint-cua-step-CA>
# Tạo thư mục TLS
mkdir -p /opt/gitea/ssl
# Cấp certificate
step ca certificate "gitea.hoatranlabs.local" \
/opt/gitea/ssl/cert.pem \
/opt/gitea/ssl/key.pem \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--provisioner acme \
--san gitea.hoatranlabs.local \
--san 10.11.45.40
# Container Gitea chạy bằng uid/gid 1000 (USER_UID/USER_GID) nên phải đọc được cert và key
chown root:1000 /opt/gitea/ssl/cert.pem /opt/gitea/ssl/key.pem
chmod 640 /opt/gitea/ssl/cert.pem /opt/gitea/ssl/key.pem
# Trust root CA cho Docker (cần pull từ Harbor)
step ca root /usr/local/share/ca-certificates/hoatranlabs-root.crt
update-ca-certificates
# Phân phối cert cho Docker daemon trust harbor.hoatranlabs.local
mkdir -p /etc/docker/certs.d/harbor.hoatranlabs.local/
cp /usr/local/share/ca-certificates/hoatranlabs-root.crt \
/etc/docker/certs.d/harbor.hoatranlabs.local/ca.crt
systemctl restart docker
3.1 Tự Động Gia Hạn Cert
cat > /etc/systemd/system/gitea-cert-renew.service << 'EOF'
[Unit]
Description=Renew Gitea TLS certificate from step-CA
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/bin/step ca renew \
/opt/gitea/ssl/cert.pem \
/opt/gitea/ssl/key.pem \
--force \
--ca-url https://step-ca.hoatranlabs.local:9000
ExecStartPost=/usr/bin/docker compose -f /opt/gitea/docker-compose.yml restart gitea
EOF
cat > /etc/systemd/system/gitea-cert-renew.timer << 'EOF'
[Unit]
Description=Renew Gitea TLS certificate daily
[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=1800
Persistent=true
[Install]
WantedBy=timers.target
EOF
systemctl daemon-reload
systemctl enable --now gitea-cert-renew.timer
Triển Khai Gitea Qua Docker Compose
File docker-compose.yml
mkdir -p /opt/gitea
cd /opt/gitea
4.1 File docker-compose.yml
# Docker Compose v2 trở lên (plugin của repo Docker) coi khóa `version:` là lỗi thời và chỉ cảnh báo, nên không khai báo
services:
# ─── PostgreSQL 16 ──────────────────────────────────────────────────────────
db:
image: postgres:16-alpine
container_name: gitea-db
restart: unless-stopped
environment:
POSTGRES_DB: gitea
POSTGRES_USER: gitea
POSTGRES_PASSWORD: Gitea@DB2024!
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- gitea_net
healthcheck:
test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
interval: 10s
timeout: 5s
retries: 5
logging:
driver: journald
options:
tag: gitea-db
# ─── Gitea ──────────────────────────────────────────────────────────────────
gitea:
image: gitea/gitea:28.1.0 # ghim phiên bản ổn định (tag có trên Docker Hub), không dùng :latest
container_name: gitea
restart: unless-stopped
environment:
# User/group mapping
USER_UID: "1000"
USER_GID: "1000"
# Database
GITEA__database__DB_TYPE: postgres
GITEA__database__HOST: db:5432
GITEA__database__NAME: gitea
GITEA__database__USER: gitea
GITEA__database__PASSWD: Gitea@DB2024!
GITEA__database__SSL_MODE: disable
# Server
GITEA__server__DOMAIN: gitea.hoatranlabs.local
GITEA__server__SSH_DOMAIN: gitea.hoatranlabs.local
GITEA__server__HTTP_PORT: "3000"
GITEA__server__ROOT_URL: https://gitea.hoatranlabs.local/
GITEA__server__PROTOCOL: https
GITEA__server__CERT_FILE: /data/gitea/ssl/cert.pem
GITEA__server__KEY_FILE: /data/gitea/ssl/key.pem
# SSH do OpenSSH có sẵn trong image xử lý (map 2222:22), không bật built-in SSH server;
# SSH_PORT chỉ là cổng hiển thị trong URL clone
GITEA__server__SSH_PORT: "2222"
# Security
GITEA__security__SECRET_KEY: Ch4ng3Th1sT0Rand0mValu3Immediately!
GITEA__security__INTERNAL_TOKEN: Ch4ng3Th1sT0k3nAlso!!!!!!!!!!!!!!
GITEA__security__INSTALL_LOCK: "true"
GITEA__security__PASSWORD_COMPLEXITY: lower,upper,digit,spec
GITEA__security__MIN_PASSWORD_LENGTH: "12"
# Webhook gửi tới đích nội bộ: Gitea 28 (EGRESS_MODE=lax mặc định) chỉ cho gọi địa chỉ private nằm trong danh sách này
# ([webhook] ALLOWED_HOST_LIST cũ đã deprecated từ v28.0.0). ArgoCD (VIP Traefik, bài 29) và Mattermost (bài 37), đều cổng 443
GITEA__security__EGRESS_MODE: lax
GITEA__security__ALLOWED_HOST_LIST: "10.11.65.100:443,10.11.65.57:443"
# Service
GITEA__service__DISABLE_REGISTRATION: "true"
GITEA__service__REQUIRE_SIGNIN_VIEW: "true"
GITEA__service__DEFAULT_KEEP_EMAIL_PRIVATE: "true"
GITEA__service__NO_REPLY_ADDRESS: [email protected]
# Mailer (relay qua Mailu VM246)
GITEA__mailer__ENABLED: "true"
GITEA__mailer__SMTP_ADDR: mailu.hoatranlabs.local
GITEA__mailer__SMTP_PORT: "587"
GITEA__mailer__FROM: [email protected]
GITEA__mailer__USER: [email protected]
GITEA__mailer__PASSWD: Noreply@Mailu2024!
GITEA__mailer__PROTOCOL: smtp+starttls
# OAuth2 (Authentik)
GITEA__oauth2__ENABLED: "true"
GITEA__oauth2__JWT_SECRET: Ch4ng3Th1sJwtS3cr3t123456789012
# Actions (CI/CD)
GITEA__actions__ENABLED: "true"
# github = lấy action (actions/checkout...) từ github.com; self = từ chính Gitea này (phải mirror từng action)
GITEA__actions__DEFAULT_ACTIONS_URL: github
# Cache
GITEA__cache__ADAPTER: redis
GITEA__cache__HOST: "network=tcp,addr=redis:6379,db=0"
# Queue
GITEA__queue__TYPE: redis
GITEA__queue__CONN_STR: "network=tcp,addr=redis:6379,db=1"
# Session
GITEA__session__PROVIDER: redis
GITEA__session__PROVIDER_CONFIG: "network=tcp,addr=redis:6379,db=2"
# Log
GITEA__log__LEVEL: Info
GITEA__log__MODE: console
ports:
- "443:3000"
- "2222:22"
volumes:
- gitea_data:/data
- /opt/gitea/ssl:/data/gitea/ssl:ro
# Root CA step-CA để Gitea tin cert của Authentik (OIDC) và Mailu (SMTP STARTTLS)
- /usr/local/share/ca-certificates/hoatranlabs-root.crt:/etc/ssl/certs/hoatranlabs-root.crt:ro
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
networks:
- gitea_net
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
logging:
driver: journald
options:
tag: gitea
# ─── Redis (cache + queue + session) ────────────────────────────────────────
redis:
image: redis:7-alpine
container_name: gitea-redis
restart: unless-stopped
command: redis-server --save 60 1 --loglevel warning
volumes:
- redis_data:/data
networks:
- gitea_net
logging:
driver: journald
options:
tag: gitea-redis
# ─── Gitea Actions Runner ────────────────────────────────────────────────────
gitea-runner:
image: gitea/runner:5.1.0 # act_runner đã đổi tên thành Gitea Runner (image gitea/runner); ghim phiên bản thay vì :latest
container_name: gitea-runner
restart: unless-stopped
environment:
GITEA_INSTANCE_URL: https://gitea.hoatranlabs.local
GITEA_RUNNER_REGISTRATION_TOKEN: "__REPLACE_WITH_TOKEN_FROM_GITEA__"
GITEA_RUNNER_NAME: runner-node2
# Job chạy trong image runner-images (Ubuntu có sẵn git, Node, Docker CLI + buildx); biến này ưu tiên hơn runner.labels trong config.yaml nên giữ hai nơi giống nhau
GITEA_RUNNER_LABELS: "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"
# Chỉ bỏ comment sau khi đã tạo /opt/gitea/runner/config.yaml (mục 8.3); file chưa tồn tại thì runner không đăng ký được
# CONFIG_FILE: /data/config.yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- runner_data:/data
- /opt/gitea/ssl/cert.pem:/etc/ssl/certs/gitea-ca.crt:ro
- /usr/local/share/ca-certificates/hoatranlabs-root.crt:/usr/local/share/ca-certificates/hoatranlabs-root.crt:ro
networks:
- gitea_net
depends_on:
- gitea
logging:
driver: journald
options:
tag: gitea-runner
volumes:
gitea_data:
driver: local
driver_opts:
type: none
o: bind
device: /opt/gitea/data
postgres_data:
driver: local
driver_opts:
type: none
o: bind
device: /opt/gitea/postgres
redis_data:
driver: local
driver_opts:
type: none
o: bind
device: /opt/gitea/redis
runner_data:
driver: local
driver_opts:
type: none
o: bind
device: /opt/gitea/runner
networks:
gitea_net:
name: gitea_net # đặt tên cố định để runner (container.network ở mục 8.3) tham chiếu được
driver: bridge
ipam:
config:
- subnet: 172.29.0.0/24
Khởi Động Gitea Lần Đầu
# Tạo thư mục bind mount
mkdir -p /opt/gitea/{data,postgres,redis,runner}
# Tạo SECRET_KEY và INTERNAL_TOKEN ngẫu nhiên (thay vào docker-compose.yml)
echo "SECRET_KEY: $(openssl rand -hex 32)"
echo "INTERNAL_TOKEN: $(openssl rand -hex 32)"
echo "JWT_SECRET: $(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')" # JWT_SECRET phải là base64 URL-safe của đúng 32 byte
# → Thay các giá trị "Ch4ng3..." trong docker-compose.yml bằng output trên
# Khởi động (không bao gồm runner vì chưa có token)
docker compose up -d db redis gitea
# Theo dõi logs
docker compose logs -f gitea --tail=50
# Đợi Gitea sẵn sàng (~60 giây)
# /api/healthz không cần đăng nhập (trang chủ chuyển hướng sang đăng nhập vì REQUIRE_SIGNIN_VIEW=true)
until curl -sk https://10.11.45.40/api/healthz | grep -q pass; do
echo "Waiting for Gitea..."
sleep 5
done
echo "Gitea is up!"
Cấu Hình Ban Đầu Qua Web UI
File compose của bài đã đặt sẵn INSTALL_LOCK: "true" cùng toàn bộ thông số database/server qua biến môi trường, nên Gitea bỏ qua trang Installation: truy cập https://gitea.hoatranlabs.local sẽ vào thẳng trang đăng nhập và chưa có tài khoản nào. Các thông số sau đã được nạp tự động (chỉ để đối chiếu, không cần nhập lại):
Database: PostgreSQL
Host: db:5432
Username: gitea
Password: Gitea@DB2024!
Database name: gitea
Site Title: HOATRANLABS Gitea
Repository Root: /data/git/repositories
SSH Server: gitea.hoatranlabs.local:2222
Tạo tài khoản quản trị gitadmin bằng CLI (thay cho form Installation; mật khẩu thỏa PASSWORD_COMPLEXITY và MIN_PASSWORD_LENGTH đã đặt ở compose):
docker exec -u git gitea gitea admin user create --admin --username gitadmin --password 'Admin@Gitea2024!' --email [email protected] --must-change-password=false
Bot cho ArgoCD (bài 29): tạo user argocd-bot kèm access token (lệnh in token ra, lưu lại). Repo k8s-manifests do gitadmin tạo (New Repository → Owner: gitadmin, Private), sau đó thêm argocd-bot làm Collaborator quyền Read:
docker exec -u git gitea gitea admin user create --username argocd-bot --password 'Hoatran@2024!' --email [email protected] --must-change-password=false --access-token
Tích Hợp Authentik SSO (OIDC)
Tạo OAuth2 Provider Trên Authentik (VM234) · Thêm OAuth2 Source Trong Gitea
7.1 Tạo OAuth2 Provider Trên Authentik (VM234)
Đăng nhập Authentik Admin: https://authentik.hoatranlabs.local:9443/if/admin/
- Name:
gitea-oidc - Client type: Confidential
- Redirect URIs:
https://gitea.hoatranlabs.local/user/oauth2/authentik/callback - Scopes:
openid,profile,email
- Name:
Gitea - Slug:
gitea - Provider:
gitea-oidc
# Ghi lại:
CLIENT_ID="<từ-authentik>"
CLIENT_SECRET="<từ-authentik>"
7.2 Thêm OAuth2 Source Trong Gitea
Gitea Admin → Site Administration → Authentication Sources → Add Authentication Source:
Authentication Type: OAuth2
Name: authentik
OAuth2 Provider: OpenID Connect
Client ID: <CLIENT_ID>
Client Secret: <CLIENT_SECRET>
OpenID Connect Auto Discovery URL:
https://authentik.hoatranlabs.local:9443/application/o/gitea/.well-known/openid-configuration
Scopes: openid profile email
Required Claim Name: (để trống)
Group Claim Name: groups
Admin Group: gitea-admins
Restricted Group: (để trống)
Icon URL: https://authentik.hoatranlabs.local:9443/static/dist/assets/icons/icon.png
Skip local 2FA: OFF
Lưu lại → đăng xuất → Sign In with Authentik để kiểm tra.
Đăng Ký Gitea Actions Runner
Lấy Registration Token · Khởi Động Runner · Cấu Hình Runner Nâng Cao (tùy chọn)
8.1 Lấy Registration Token
Gitea Admin → Site Administration → Runners → Create new runner
→ Copy token vào docker-compose.yml tại GITEA_RUNNER_REGISTRATION_TOKEN
8.2 Khởi Động Runner
cd /opt/gitea
# Cập nhật token trong docker-compose.yml, sau đó khởi động runner
docker compose up -d gitea-runner
# Xác nhận runner đã đăng ký
docker compose logs gitea-runner --tail=20
# Kiểm tra trong Gitea Admin UI:
# Site Administration → Runners → runner-node2 (status: Online)
8.3 Cấu Hình Runner Nâng Cao (tùy chọn)
Các khóa tinh chỉnh (capacity, cache, timeout...) là tùy chọn, nhưng runner.envs, container.options và container.valid_volumes dưới đây là BẮT BUỘC nếu chạy workflow mẫu ở mục 9.2: job container phải tin root CA step-CA (để checkout từ Gitea, gọi API Gitea, push lên Harbor) và cần Docker CLI. Image runner-images ở labels đã có sẵn git, Node, Docker CLI và buildx; runner tự mount docker.sock của VM240 vào mọi job container (khi docker_host để trống) nên không cần khai báo thêm.
# Tạo file config cho runner
cat > /opt/gitea/runner/config.yaml << 'EOF'
log:
level: info
runner:
file: .runner
capacity: 5
env_file: .env
timeout: 3h
insecure: false
fetch_timeout: 5s
fetch_interval: 2s
# JS action (checkout, metadata-action...) dùng bundle CA riêng của Node nên phải trỏ NODE_EXTRA_CA_CERTS tới bundle đã mount ở container.options
envs:
NODE_EXTRA_CA_CERTS: /etc/ssl/certs/ca-certificates.crt
labels:
- "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
- "ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"
# Đây là image của job container, độc lập với Ubuntu của VM240. Cần chạy workflow cũ ghim ubuntu-22.04 thì thêm lại
# nhãn "ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04" ở cả config.yaml lẫn GITEA_RUNNER_LABELS (tag có trên Docker Hub, kiểm 2026-10-15)
cache:
enabled: true
dir: /data/.cache/actcache
host: ""
port: 0
external_server: ""
container:
network: gitea_net
privileged: false
# -v: mount bundle CA của VM240 (đã gồm root CA step-CA nhờ update-ca-certificates ở mục 3) đè lên bundle trong job container,
# để git, curl, openssl, docker CLI trong job tin cert của Gitea và Harbor; nguồn mount phải khớp valid_volumes (đường dẫn trên VM240)
options: "--add-host=harbor.hoatranlabs.local:10.11.45.39 --add-host=gitea.hoatranlabs.local:10.11.45.40 -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro"
workdir_parent: /data/act
valid_volumes:
- /cache
- /etc/ssl/certs/ca-certificates.crt:ro
docker_host: "" # để trống: runner tự mount /var/run/docker.sock của VM240 vào job container
force_pull: false
host:
workdir_parent: ""
EOF
Sau đó bỏ comment dòng CONFIG_FILE của service gitea-runner trong docker-compose.yml rồi chạy lại docker compose up -d gitea-runner để runner dùng file config này.
Pipeline CI/CD — Ví Dụ Thực Tế
Cấu Hình Harbor Credentials Trong Gitea Secrets · Workflow: Build và Push Image Lên Harbor · Workflow: Deploy Lên PVE Sau Build
9.1 Cấu Hình Harbor Credentials Trong Gitea Secrets
Gitea → Repo hoặc Org → Settings → Secrets → Actions:
HARBOR_USER = robot$gitea-ci
HARBOR_PASS = <token-từ-harbor-robot-account>
HARBOR_URL = harbor.hoatranlabs.local
9.2 Workflow: Build và Push Image Lên Harbor
Lưu tại .gitea/workflows/build-push.yml trong repo:
name: Build and Push Docker Image
on:
push:
branches:
- main
- develop
tags:
- 'v*'
pull_request:
branches:
- main
env:
REGISTRY: harbor.hoatranlabs.local
IMAGE_NAME: apps/myapp
jobs:
build-and-push:
runs-on: ubuntu-latest
steps:
- name: Checkout source code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
with:
driver: docker # build bằng dockerd của VM240 (đã tin root CA ở /etc/docker/certs.d/harbor...), không tạo BuildKit container riêng
- name: Extract metadata for Docker
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha,prefix=sha-,format=short
- name: Login to Harbor Registry
if: github.event_name != 'pull_request'
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ secrets.HARBOR_USER }}
password: ${{ secrets.HARBOR_PASS }}
- name: Build and push Docker image
uses: docker/build-push-action@v5
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
# Không dùng cache type=registry: driver docker chỉ hỗ trợ khi bật containerd image store;
# layer đã được cache sẵn trong dockerd của VM240 giữa các lần chạy
- name: Notify on failure
if: failure()
uses: actions/github-script@v7
with:
script: |
core.setFailed('Build or push failed — check Harbor and runner logs')
Workflow chạy trong job container docker.gitea.com/runner-images:ubuntu-latest của runner (cấu hình ở mục 8.3): image có sẵn git, Node, Docker CLI và buildx, job nhận docker.sock của VM240 và bundle CA đã gồm root CA step-CA, nên actions/checkout clone được từ gitea.hoatranlabs.local và docker/login-action đăng nhập được Harbor. Mount docker.sock cho job tương đương quyền root trên VM240, chấp nhận trong lab; muốn cách ly hơn thì dùng image gitea/runner:5.1.0-dind (cần privileged: true) theo tài liệu Gitea Runner.
9.3 Workflow: Deploy Lên PVE Sau Build
Gitea 28.1.0 hỗ trợ trigger workflow_run (types requested, in_progress, completed; lọc được theo workflows và branches). Như trên GitHub, file workflow này phải nằm ở nhánh mặc định (main) thì mới được kích hoạt.
name: Deploy to Lab Infrastructure
on:
workflow_run:
workflows: ["Build and Push Docker Image"]
types:
- completed
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
if: ${{ github.event.workflow_run.conclusion == 'success' }}
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Deploy via SSH to target VM
uses: appleboy/[email protected]
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_SSH_KEY }}
script: |
cd /opt/myapp
docker compose pull
docker compose up -d --remove-orphans
docker system prune -f
- name: Health check
run: |
sleep 15
curl -fsSL https://${{ secrets.DEPLOY_HOST }}:8080/health \
|| (echo "Health check failed!" && exit 1)
9.4 Cấu Hình Deploy SSH Key
# Tạo SSH key pair cho deploy
ssh-keygen -t ed25519 -C "[email protected]" \
-f /tmp/gitea-deploy-key \
-N ""
# Thêm public key vào target VM
cat /tmp/gitea-deploy-key.pub
# → Thêm dòng này vào ~/.ssh/authorized_keys trên target VM
# Thêm private key vào Gitea Secrets
# DEPLOY_SSH_KEY = nội dung /tmp/gitea-deploy-key
# DEPLOY_HOST = IP hoặc hostname của target VM
# DEPLOY_USER = username SSH
DNS Và Firewall
DNS Pi-hole (VM247) · Firewall Rules
10.1 DNS Pi-hole (VM247)
# SSH vào VM247
ssh [email protected]
# Thêm A record (Pi-hole chạy trong Docker, bài 12):
# Admin UI → Settings → Local DNS Records: gitea.hoatranlabs.local → 10.11.45.40
# hoặc chạy script ở bài 12 (đã có sẵn record gitea):
/opt/pihole/scripts/add_dns_records.sh
docker exec pihole pihole reloaddns
# Kiểm tra
nslookup gitea.hoatranlabs.local 10.11.45.53
10.2 Firewall Rules
# VLAN_MGMT truy cập Gitea web
ALLOW TCP 10.11.45.0/24 10.11.45.40 443 # HTTPS Gitea UI/API
ALLOW TCP 10.11.45.0/24 10.11.45.40 2222 # SSH git clone/push
# VLAN_SRV và SEC có thể clone nhưng không push (tùy policy)
ALLOW TCP 10.11.25.0/24 10.11.45.40 443
ALLOW TCP 10.11.65.0/24 10.11.45.40 443
# Runner cần kết nối Harbor để push image
# (VM240 → VM239: đã trong VLAN_MGMT, không cần rule thêm)
# Chặn truy cập từ Internet
DENY any WAN 10.11.45.40 any
Backup Gitea
cat > /opt/gitea/backup-gitea.sh << 'SCRIPT'
#!/bin/bash
set -e
BACKUP_DIR="/backup/gitea"
DATE=$(date +%Y%m%d-%H%M)
mkdir -p "$BACKUP_DIR"
echo "[$(date)] Creating Gitea backup..."
cd /opt/gitea
# Gitea có lệnh backup built-in
docker exec -u git gitea \
gitea admin dump \
--file /data/gitea-backup-$DATE.zip \
--type zip
# Copy ra ngoài container
docker cp gitea:/data/gitea-backup-$DATE.zip \
"$BACKUP_DIR/gitea-backup-$DATE.zip"
# Cleanup trong container
docker exec gitea rm -f /data/gitea-backup-$DATE.zip
# PostgreSQL dump riêng
docker exec gitea-db pg_dump -U gitea gitea \
> "$BACKUP_DIR/gitea-db-$DATE.sql"
# Giữ 7 bản gần nhất
find "$BACKUP_DIR" -name "gitea-backup-*.zip" -mtime +7 -delete
find "$BACKUP_DIR" -name "gitea-db-*.sql" -mtime +7 -delete
echo "[$(date)] Backup complete: gitea-backup-$DATE.zip"
SCRIPT
chmod +x /opt/gitea/backup-gitea.sh
# Cron job 4:30 sáng mỗi ngày
(crontab -l 2>/dev/null; echo "30 4 * * * /opt/gitea/backup-gitea.sh >> /var/log/gitea-backup.log 2>&1") \
| crontab -
Troubleshooting
Gitea Không Khởi Động Được · OIDC Login Authentik Không Hoạt Động · Runner Không Nhận Job
12.1 Gitea Không Khởi Động Được
# Kiểm tra containers
docker compose ps
docker compose logs gitea --tail=100
# Lỗi phổ biến: DB chưa sẵn sàng khi Gitea start
docker compose logs db --tail=30
docker compose restart gitea
# Kiểm tra quyền thư mục data
ls -la /opt/gitea/data/
chown -R 1000:1000 /opt/gitea/data/
12.2 OIDC Login Authentik Không Hoạt Động
# Kiểm tra discovery endpoint
curl -sk \
https://authentik.hoatranlabs.local:9443/application/o/gitea/.well-known/openid-configuration \
| python3 -m json.tool | head -20
# Kiểm tra redirect URI trong Authentik khớp với Gitea
# Đúng: https://gitea.hoatranlabs.local/user/oauth2/authentik/callback
# Sai: http://gitea.hoatranlabs.local/... hoặc sai path
# Log trong Gitea
docker compose logs gitea | grep -i "oauth\|oidc\|authentik"
12.3 Runner Không Nhận Job
# Kiểm tra runner đã đăng ký và online
docker compose logs gitea-runner --tail=50
# Token hết hạn? Tạo token mới trong Gitea Admin → Runners
# Cập nhật token trong docker-compose.yml → recreate runner
docker compose rm -f gitea-runner
# Sửa token trong docker-compose.yml
docker compose up -d gitea-runner
# Kiểm tra runner có kết nối được Gitea không
docker exec gitea-runner \
curl -sk https://gitea.hoatranlabs.local/api/v1/repos/search | head -c 100
12.4 Runner Không Pull Được Image Từ Harbor
# Kiểm tra CA trust trong runner container
docker exec gitea-runner \
curl -sk https://harbor.hoatranlabs.local/api/v2.0/systeminfo | python3 -m json.tool
# Nếu lỗi certificate:
# Đảm bảo volume mount CA cert vào runner (đã có trong docker-compose.yml)
# Kiểm tra:
docker exec gitea-runner ls /usr/local/share/ca-certificates/
docker exec gitea-runner update-ca-certificates
# Recreate runner sau khi fix
docker compose restart gitea-runner
# Kiểm tra từ một job container (cùng image và cùng mount bundle CA như mục 8.3):
docker run --rm -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro \
docker.gitea.com/runner-images:ubuntu-latest curl -sS https://harbor.hoatranlabs.local/api/v2.0/systeminfo
12.5 SSH Git Clone Không Được
# Kiểm tra port 2222 đang được lắng nghe
ss -tlnp | grep 2222
# Test SSH connection
ssh -T -p 2222 [email protected]
# Lỗi "Host key verification failed":
ssh-keyscan -p 2222 gitea.hoatranlabs.local >> ~/.ssh/known_hosts
# Cấu hình SSH config cho tiện
cat >> ~/.ssh/config << 'EOF'
Host gitea.hoatranlabs.local
HostName gitea.hoatranlabs.local
Port 2222
User git
IdentityFile ~/.ssh/id_ed25519
EOF
12.6 Hết Dung Lượng Disk
# Kiểm tra dung lượng
df -h /opt/gitea/
du -sh /opt/gitea/*
# Xóa Git LFS objects không dùng (nếu LFS được bật): Gitea không có lệnh CLI cho việc này,
# dùng cron task "Garbage collect LFS pointers in repositories" (gc_lfs, mặc định tắt) trong Site Administration
# Dọn dẹp Docker volumes không cần thiết
docker system prune -f
docker volume prune -f
# Git GC cho tất cả repos (repo nằm ở /data/git/repositories trong container)
docker exec -u git gitea sh -c 'for r in /data/git/repositories/*/*.git; do git -C "$r" gc --prune=now; done'
Checklist Hoàn Thành
- VM240 tạo trên node2, tag VLAN 45, IP 10.11.45.40, disk 50 GB
- Ubuntu Server 24.04 LTS cài đặt, Docker CE hoạt động (cài từ repo
noble,docker compose versionchạy được) - step-CA cert cấp cho
gitea.hoatranlabs.local, systemd timer gia hạn tự động - Root CA của step-CA trust trên VM240 và trong Docker daemon
- Thư mục
/opt/gitea/{data,postgres,redis,runner}tạo xong -
SECRET_KEY,INTERNAL_TOKEN,JWT_SECRETthay bằng giá trị ngẫu nhiên -
docker compose up -d db redis gitea— 3 containers healthy - Truy cập
https://gitea.hoatranlabs.localthành công, admin account tạo xong - OAuth2 Source Authentik cấu hình, login SSO thành công
- Runner registration token lấy từ Gitea Admin
-
docker compose up -d gitea-runner— runner online trong Gitea Admin UI -
/opt/gitea/runner/config.yamlcórunner.envs,container.optionsmount bundle CA vàvalid_volumes; đã bỏ commentCONFIG_FILE(mục 8.3) - Harbor credentials (
HARBOR_USER,HARBOR_PASS) thêm vào Gitea Secrets - Test workflow
.gitea/workflows/build-push.ymlchạy thành công - Image xuất hiện trong Harbor project
apps - DNS record
gitea.hoatranlabs.local → 10.11.45.40thêm vào Pi-hole - SSH clone qua port 2222 hoạt động
- SMTP relay qua Mailu (VM246) — Gitea gửi email thông báo thành công
- Firewall rules VLAN_MGMT → port 443, 2222 allowed
- Backup script và cron job
/opt/gitea/backup-gitea.shthiết lập - PBS snapshot job cho VM240 tạo trên PVE (storage
pbs-primary)
Tài liệu tham khảo (đã dùng khi cập nhật lên Ubuntu 24.04, kiểm 2026-10-15):
- Docker Engine trên Ubuntu (repo apt, deb822): https://docs.docker.com/engine/install/ubuntu/
- Gitea: bản phát hành https://github.com/go-gitea/gitea/releases · image https://hub.docker.com/r/gitea/gitea/tags
- Gitea Runner: image https://hub.docker.com/r/gitea/runner/tags · image job https://hub.docker.com/r/gitea/runner-images/tags
- step-cli: https://github.com/smallstep/cli/releases
- Ubuntu 24.04 ISO: https://releases.ubuntu.com/24.04/
Tài liệu: HOATRANLABS Infrastructure — Gitea Git Hosting + CI/CD (Gitea Actions) trên Ubuntu 24.04 LTS
Cập nhật: 2026-10-15