solution-erp/docs/guides/cicd.md

CI/CD — Gitea Actions

Automation pipeline từ push → build → test → deploy. Chạy trên Windows self-hosted runner (cần cho WinRM + Word COM).

1. Pipeline overview

Push main
  ├─ build-backend (Windows runner)
  │   └─ dotnet restore/build/publish → artifact "backend-api"
  ├─ build-fe-admin (Ubuntu runner)
  │   └─ npm ci + npm run build → artifact "fe-admin-dist"
  ├─ build-fe-user (Ubuntu runner)
  │   └─ npm ci + npm run build → artifact "fe-user-dist"
  └─ deploy-iis (Windows runner) — chỉ khi ref = main
      ├─ download 3 artifact
      ├─ Compress-Archive → 3 zip
      ├─ Copy-Item via PSSession WinRM → target server
      └─ Invoke-Command → scripts/deploy-iis.ps1

File spec: .gitea/workflows/deploy.yml (đã có).

2. Secrets setup

Trong Gitea repo → Settings → Actions → Secrets, thêm:

Secret	Ví dụ	Mô tả
IIS_HOST	10.0.0.100	Hostname/IP target IIS server
IIS_USER	solution-erp\deploy	Windows user có admin + WinRM enabled
IIS_PASSWORD	...	Password tương ứng
JWT_SECRET	64+ random chars	Pass vào user-secrets khi deploy
DB_CONNECTION	Server=.;Database=SolutionErp;...	ConnectionString production

KHÔNG echo secret ra log (Gitea auto-mask nhưng vẫn cẩn thận).

3. Runner setup

Windows self-hosted runner (cho build BE + deploy)

Trên Windows VM:

# Download Gitea Act runner
# https://gitea.com/gitea/act_runner/releases
.\act_runner register --instance https://gitea.yourcorp.local --token <token>
.\act_runner daemon

Prereqs trên runner:

• .NET 10 SDK
• Git 2.40+
• PowerShell 7+
• Node 20 (cho test/build nếu cần BE test với FE proxy)
• WinRM client: winrm quickconfig
• Test connectivity: Test-NetConnection $env:IIS_HOST -Port 5985

Ubuntu runner (cho build FE)

# Docker runner
docker run -d --name gitea-runner \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e GITEA_INSTANCE_URL=https://gitea.yourcorp.local \
    -e GITEA_RUNNER_REGISTRATION_TOKEN=<token> \
    gitea/act_runner:latest

Prereqs:

• Node 20 (qua actions/setup-node — KHÔNG dùng latest, xem gotchas.md #5)
• npm cache

4. Branch strategy + trigger

Branch	Trigger	Action
main	push	full build + deploy production
staging	push	full build + deploy staging (nếu có)
feature/*	push	chỉ build + test, không deploy
PR merge	merge_request	build + test, optional auto-merge nếu pass
Manual	workflow_dispatch	re-deploy current main

5. Build optimizations

• Node cache qua actions/setup-node@v4 với cache: 'npm' + cache-dependency-path
• NuGet cache qua actions/cache@v4 path ~/.nuget/packages (Windows: %USERPROFILE%\.nuget\packages)
• Parallel build 3 job FE/BE độc lập

6. Pre-commit checks (Phase 5.1 — khi có thời gian)

Thêm job verify chạy trước deploy:

• dotnet format --verify-no-changes
• dotnet test (khi có unit test)
• npm run lint
• npm run build (both FE)

7. Rollback qua CI/CD

1. Gitea repo → Actions → tìm run cũ đã deploy thành công
2. Re-run job đó (re-runner download artifact cũ + deploy lại)

Hoặc revert git:

git revert <bad-commit>
git push

8. Common CI/CD issues

Problem	Fix
Node build fail trên CI nhưng OK local	🔴 .nvmrc=20 tồn tại ở fe-*/ NHƯNG CI không có bước setup-node ⇒ không được áp dụng (ghost-wire, gotcha #92)
WinRM timeout	Check firewall port 5985/5986, increase Test-NetConnection -TimeoutSec
NuGet restore slow	Add cache action
Artifact size > 100MB	Exclude bin/, obj/, node_modules/ trong dotnet publish
Deploy không thấy file mới	App pool chưa restart — xem log scripts/deploy-iis.ps1 xem Stop+Start có chạy không

9. Liên quan

• deployment-iis.md — IIS setup chi tiết
• runbook.md — operations
• .gitea/workflows/deploy.yml — workflow YAML
• scripts/deploy-iis.ps1 — deploy script