Simone/local-ci-cd-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
90a43964434b3621cd7b97cb0a33cb6fd89b375a
local-ci-cd-system/README.md
T
Simone 90a4396443 feat: enhance documentation and scripts for in-VM Git cloning and template setup 
- Updated README.md to reflect the new in-VM git clone feature with `-UseGitClone`.
- Modified Setup-Host.ps1 to correct VMX path references.
- Revised various documentation files (ARCHITECTURE.md, CI-FLOW.md, HOST-SETUP.md, WINDOWS-TEMPLATE-SETUP.md) to include updated paths and features.
- Added Setup-GiteaSSH.md for SSH configuration instructions.
- Archived outdated documentation and updated README.md for clarity on current resources.
2026-05-10 23:03:56 +02:00

221 lines
8.9 KiB
Markdown
Raw Blame History

# Local CI/CD System
Sistema CI/CD self-hosted su Windows per build isolati in VM efimere VMware.
**Stato**: production-ready — e2e verificato (e2e-009 SUCCESS); §3.3 in-VM git clone attivabile via `-UseGitClone` (e2e PASS, -25.7% vs baseline)
---
## Panoramica
Il runner [act_runner](https://gitea.com/gitea/act_runner) riceve i job da Gitea Actions.
Per ogni job, lo script `Invoke-CIJob.ps1` orchestra l'intero ciclo:
```
Gitea push/tag
│
▼
act_runner (Windows service, label: windows-build)
│
▼
Invoke-CIJob.ps1
│
├─ 1. git clone repo su host (con submoduli)
├─ 2. Linked clone da snapshot BaseClean
├─ 3. Avvio VM headless
├─ 4. Attesa WinRM ready
├─ 5. Zip transfer → build via WinRM → raccolta artifacts
├─ 6. Copia artifacts in F:\CI\Artifacts\<jobid>\
└─ finally: stop + rimozione VM clone
```
Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dallo snapshot `BaseClean` ad ogni run.
---
## Requisiti Host
| Componente | Versione / Dettaglio |
|---|---|
| OS | Windows 11 |
| CPU/RAM | i9-10900X, 64 GB RAM |
| VMware Workstation Pro | installato, `vmrun.exe` disponibile |
| PowerShell | 5.1 |
| act_runner | v1.0.2 — `F:\CI\act_runner\act_runner.exe` |
| Gitea | self-hosted `http://10.10.20.11:3100` / `https://gitea.emulab.it` |
## Template VM (snapshot `BaseClean`)
| Componente | Versione |
|---|---|
| OS | Windows Server 2025 |
| VMX | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` (path in `runner/config.yaml` → `GITEA_CI_TEMPLATE_PATH`) |
| VS Build Tools | 2026 (MSBuild 18.5.4 / toolset v145) |
| .NET SDK | 10.0.203 |
| Python | 3.13.3 |
| Rete | VMnet8 NAT — `192.168.79.0/24` |
| WinRM | HTTPS/5986, Basic auth, self-signed cert (SkipCACheck — lab-only) |
---
## Struttura repository
```
├── Setup-Host.ps1 # Bootstrap host: dirs F:\CI\, credenziali, act_runner service
├── PSScriptAnalyzerSettings.psd1 # Regole linting condivise (§5.4)
│
├── scripts/
│ ├── _Common.psm1 # Shared module (vmrun wrapper, session opts) §5.2
│ ├── Invoke-CIJob.ps1 # Orchestratore principale (-UseGitClone opt-in §3.3)
│ ├── New-BuildVM.ps1 # Linked clone da template
│ ├── Wait-VMReady.ps1 # Polling WinRM HTTPS readiness
│ ├── Invoke-RemoteBuild.ps1 # Zip transfer (o git clone in VM) + build via WinRM
│ ├── Get-BuildArtifacts.ps1 # Copia artifacts dall'host
│ ├── Remove-BuildVM.ps1 # Stop + rimozione VM clone (-WhatIf)
│ ├── Cleanup-OrphanedBuildVMs.ps1 # Cleanup VM orfane (§2.2)
│ ├── Invoke-RetentionPolicy.ps1 # Retention artifact + log (§2.3)
│ ├── Watch-DiskSpace.ps1 # Alert spazio libero F: (§4.3)
│ ├── Watch-RunnerHealth.ps1 # Health check runner (§2.7)
│ ├── Backup-CITemplate.ps1 # Backup VMDK template (§2.6)
│ ├── Set-TemplateSharedFolders.ps1 # Cache NuGet/pip via shared folders (§3.1)
│ ├── Measure-CIBenchmark.ps1 # Benchmark fasi pipeline (§3.6)
│ └── Register-CIScheduledTasks.ps1 # Task Scheduler bootstrap
│
├── template/
│ ├── Deploy-WinBuild2025.ps1 # Install Windows unattended + OS hardening (HOST)
│ ├── Prepare-WinBuild2025.ps1 # Provisioning template VM (HOST-side)
│ ├── Setup-WinBuild2025.ps1 # Installazione toolchain nella VM (GUEST-side)
│ ├── Validate-DeployState.ps1 # Validazione stato post-Deploy
│ └── Validate-SetupState.ps1 # Validazione stato post-Setup (pre-snapshot)
│
├── tests/ # Pester v5 unit tests (§5.1)
│
├── gitea/
│ ├── workflows/
│ │ ├── build-nsis.yml # Workflow live per nsis-plugin-nsinnounp
│ │ └── lint.yml # PSScriptAnalyzer su push/PR (§5.4)
│ └── workflow-example.yml # Template generico adattabile
│
├── runner/
│ ├── config.yaml # Configurazione act_runner (no secrets)
│ └── Install-Runner.ps1
│
├── docs/
│ ├── ARCHITECTURE.md # Diagramma sistema e componenti
│ ├── CI-FLOW.md # Flusso dettagliato passo-passo
│ ├── HOST-SETUP.md # Bootstrap macchina host
│ ├── WINDOWS-TEMPLATE-SETUP.md # Provisioning template Windows
│ ├── LINUX-TEMPLATE-SETUP.md # Bozza template Linux (§6.1, non implementato)
│ ├── OPTIMIZATION.md # Layout disco, snapshot, cache, tuning
│ ├── BEST-PRACTICES.md # Sicurezza, WinRM, credenziali, threat model
│ ├── RUNBOOK.md # Triage incident comuni (§4.4)
│ ├── TEST-PLAN-v1.3-to-HEAD.md # Test plan completo features post-v1.3
│ ├── Setup-GiteaSSH.md # Configurazione SSH alias per Gitea
│ └── archived/ # Doc storici / sign-off
│
└── TODO.md # Roadmap, audit trail task completati, backlog
```
---
## Setup rapido
### 1. Template VM
```powershell
# Dalla directory template/, dopo aver installato Windows Server 2025 nella VM
# e annotato il suo IP DHCP su VMnet8:
.\Prepare-WinBuild2025.ps1 -VMIPAddress 192.168.79.x -SkipWindowsUpdate
```
Poi spegni la VM e prendi lo snapshot con nome esatto **`BaseClean`**.
### 2. Credenziali guest
```powershell
# PowerShell elevato — una volta sola sull'host
Import-Module CredentialManager
New-StoredCredential -Target "BuildVMGuest" -UserName "ci_build" `
-Password "<your-build-password>" -Persist LocalMachine
```
### 3. act_runner
```powershell
# Registra il runner con Gitea (interattivo, usa il registration token da Gitea Admin)
F:\CI\act_runner\act_runner.exe register
# Installa come servizio Windows
nssm install act_runner "F:\CI\act_runner\act_runner.exe" daemon
nssm start act_runner
```
Imposta `GITEA_CI_TEMPLATE_PATH` nelle variabili d'ambiente del servizio:
`F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
Dettagli completi: [docs/HOST-SETUP.md](docs/HOST-SETUP.md).
### 4. SSH per Gitea
Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `gitea-ci`
(SSH port 2222, usato dai workflow live in `git clone ssh://gitea-ci/...`).
---
## Uso — build manuale (test)
```powershell
& 'N:\Code\Workspace\Local-CI-CD-System\scripts\Invoke-CIJob.ps1' `
-JobId 'test-001' `
-RepoUrl 'ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git' `
-Branch 'main' `
-Commit '' `
-TemplatePath 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
-Submodules `
-BuildCommand 'python build_plugin.py --final --dist-dir dist' `
-GuestArtifactSource 'dist' `
-GuestCredentialTarget 'BuildVMGuest'
```
Artifacts raccolti in: `F:\CI\Artifacts\test-001\artifacts.zip`.
Aggiungi `-UseGitClone` per clonare direttamente in VM (skip host-zip-transfer; richiede Git+7-Zip in template — già inclusi nel Tier-1 Toolchain §6.6).
---
## Workflow Gitea
Il file [gitea/workflows/build-nsis.yml](gitea/workflows/build-nsis.yml) è il workflow
attivo per `Simone/nsis-plugin-nsinnounp`. Si attiva su push di tag `v*` o manualmente.
Per adattarlo ad altri repository, copia [gitea/workflow-example.yml](gitea/workflow-example.yml)
e aggiorna `-RepoUrl`, `-BuildCommand` e `-GuestArtifactSource`.
---
## Documentazione
| File | Contenuto |
|---|---|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Diagramma componenti e flusso dati |
| [docs/CI-FLOW.md](docs/CI-FLOW.md) | Descrizione dettagliata di ogni fase del pipeline |
| [docs/HOST-SETUP.md](docs/HOST-SETUP.md) | Bootstrap macchina host (Setup-Host.ps1) |
| [docs/WINDOWS-TEMPLATE-SETUP.md](docs/WINDOWS-TEMPLATE-SETUP.md) | Provisioning template Windows (Deploy + Prepare + Setup) |
| [docs/LINUX-TEMPLATE-SETUP.md](docs/LINUX-TEMPLATE-SETUP.md) | Bozza template Linux (§6.1, non implementato) |
| [docs/OPTIMIZATION.md](docs/OPTIMIZATION.md) | Layout NVMe, snapshot strategy, cache, tuning |
| [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md) | Sicurezza WinRM, threat model, credenziali |
| [docs/RUNBOOK.md](docs/RUNBOOK.md) | Triage incident comuni (runner offline, clone fail, ecc.) |
| [docs/TEST-PLAN-v1.3-to-HEAD.md](docs/TEST-PLAN-v1.3-to-HEAD.md) | Test plan completo features post-v1.3 |
| [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) | Configurazione SSH alias `gitea-ci` |
| [TODO.md](TODO.md) | Roadmap, audit trail task completati, backlog |
---
## Note di sicurezza
WinRM usa **HTTPS/5986** con certificato self-signed e Basic auth.
`-SkipCACheck`/`-SkipCNCheck` sono accettabili in lab isolato (il cert non è di una CA trusted).
Per ambienti condivisi o di produzione, usare un certificato CA valida e rimuovere `-SkipCACheck`.
Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md).
Reference in New Issue View Git Blame Copy Permalink