# 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:
```powershell
# 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)

```bash
# 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`](../gotchas.md))
- 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:
```bash
git revert <bad-commit>
git push
```

## 8. Common CI/CD issues

| Problem | Fix |
|---|---|
| Node build fail trên CI nhưng OK local | Pin Node 20 qua `.nvmrc` (gotcha #5) |
| 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`](deployment-iis.md) — IIS setup chi tiết
- [`runbook.md`](runbook.md) — operations
- `.gitea/workflows/deploy.yml` — workflow YAML
- `scripts/deploy-iis.ps1` — deploy script