Simone/local-ci-cd-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: enhance documentation and scripts for in-VM Git cloning and template setup

Browse Source 
- 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.
This commit is contained in:
Simone
2026-05-10 23:03:56 +02:00
parent a60f7a4b90
commit 90a4396443
12 changed files with 114 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+51 -19
View File
@@ -2,7 +2,7 @@
Sistema CI/CD self-hosted su Windows per build isolati in VM efimere VMware. Sistema CI/CD self-hosted su Windows per build isolati in VM efimere VMware.
**Stato**: production-ready — e2e verificato (e2e-009 SUCCESS) **Stato**: production-ready — e2e verificato (e2e-009 SUCCESS); §3.3 in-VM git clone attivabile via `-UseGitClone` (e2e PASS, -25.7% vs baseline)
--- ---
@@ -49,7 +49,7 @@ Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dall
| Componente | Versione | | Componente | Versione |
|---|---| |---|---|
| OS | Windows Server 2025 | | OS | Windows Server 2025 |
| VMX | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` | | 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) | | VS Build Tools | 2026 (MSBuild 18.5.4 / toolset v145) |
| .NET SDK | 10.0.203 | | .NET SDK | 10.0.203 |
| Python | 3.13.3 | | Python | 3.13.3 |
@@ -62,36 +62,58 @@ Ogni build gira in una VM Windows Server 2025 **usa e getta**, ripristinata dall
``` ```
├── Setup-Host.ps1 # Bootstrap host: dirs F:\CI\, credenziali, act_runner service ├── Setup-Host.ps1 # Bootstrap host: dirs F:\CI\, credenziali, act_runner service
├── PSScriptAnalyzerSettings.psd1 # Regole linting condivise (§5.4)
│ │
├── scripts/ ├── scripts/
│ ├── Invoke-CIJob.ps1 # Orchestratore principale │ ├── _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 │ ├── New-BuildVM.ps1 # Linked clone da template
│ ├── Wait-VMReady.ps1 # Polling WinRM readiness │ ├── Wait-VMReady.ps1 # Polling WinRM HTTPS readiness
│ ├── Invoke-RemoteBuild.ps1 # Zip transfer + esecuzione build in VM │ ├── Invoke-RemoteBuild.ps1 # Zip transfer (o git clone in VM) + build via WinRM
│ ├── Get-BuildArtifacts.ps1 # Copia artifacts dall'host │ ├── Get-BuildArtifacts.ps1 # Copia artifacts dall'host
│ └── Remove-BuildVM.ps1 # Stop + rimozione VM clone │ ├── 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/ ├── template/
│ ├── Prepare-WinBuild2025.ps1 # Provisioning automatico template VM (HOST-side) │ ├── Deploy-WinBuild2025.ps1 # Install Windows unattended + OS hardening (HOST)
│ └── Setup-WinBuild2025.ps1 # Installazione toolchain nella VM (GUEST-side) │ ├── 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/ ├── gitea/
│ ├── workflows/ │ ├── workflows/
│ │ └── build-nsis.yml # Workflow live per nsis-plugin-nsinnounp │ │ ├── build-nsis.yml # Workflow live per nsis-plugin-nsinnounp
│ │ └── lint.yml # PSScriptAnalyzer su push/PR (§5.4)
│ └── workflow-example.yml # Template generico adattabile │ └── workflow-example.yml # Template generico adattabile
│ │
├── runner/ ├── runner/
│ └── config.yaml # Configurazione act_runner (no secrets) │ ├── config.yaml # Configurazione act_runner (no secrets)
│ └── Install-Runner.ps1
│ │
├── docs/ ├── docs/
│ ├── ARCHITECTURE.md # Diagramma sistema e componenti │ ├── ARCHITECTURE.md # Diagramma sistema e componenti
│ ├── CI-FLOW.md # Flusso dettagliato passo-passo │ ├── 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 │ ├── OPTIMIZATION.md # Layout disco, snapshot, cache, tuning
│ ├── BEST-PRACTICES.md # Sicurezza, WinRM, credenziali │ ├── BEST-PRACTICES.md # Sicurezza, WinRM, credenziali, threat model
│ └── Setup-GiteaSSH.md # Configurazione SSH alias per Gitea │ ├── 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
│ │
├── PLAN.md # Stato implementazione e decisioni tecniche └── TODO.md # Roadmap, audit trail task completati, backlog
└── TODO.md # Task completati e roadmap futura
``` ```
--- ---
@@ -131,10 +153,12 @@ nssm start act_runner
Imposta `GITEA_CI_TEMPLATE_PATH` nelle variabili d'ambiente del servizio: Imposta `GITEA_CI_TEMPLATE_PATH` nelle variabili d'ambiente del servizio:
`F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
Dettagli completi: [docs/HOST-SETUP.md](docs/HOST-SETUP.md).
### 4. SSH per Gitea ### 4. SSH per Gitea
Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `gitea-ci` Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `gitea-ci`
(SSH port 2222, necessario per `git clone ssh://gitea-ci/...` durante i build). (SSH port 2222, usato dai workflow live in `git clone ssh://gitea-ci/...`).
--- ---
@@ -153,7 +177,9 @@ Vedi [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) per configurare l'alias `g
-GuestCredentialTarget 'BuildVMGuest' -GuestCredentialTarget 'BuildVMGuest'
``` ```
Artifacts raccolti in: `F:\CI\Artifacts\test-001\artifacts.zip` 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).
--- ---
@@ -173,9 +199,15 @@ e aggiorna `-RepoUrl`, `-BuildCommand` e `-GuestArtifactSource`.
|---|---| |---|---|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Diagramma componenti e flusso dati | | [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/CI-FLOW.md](docs/CI-FLOW.md) | Descrizione dettagliata di ogni fase del pipeline |
| [docs/OPTIMIZATION.md](docs/OPTIMIZATION.md) | Layout NVMe, snapshot strategy, cache, tuning WinRM | | [docs/HOST-SETUP.md](docs/HOST-SETUP.md) | Bootstrap macchina host (Setup-Host.ps1) |
| [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md) | Sicurezza WinRM, gestione credenziali, isolamento | | [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` | | [docs/Setup-GiteaSSH.md](docs/Setup-GiteaSSH.md) | Configurazione SSH alias `gitea-ci` |
| [TODO.md](TODO.md) | Roadmap, audit trail task completati, backlog |
--- ---
@@ -185,4 +217,4 @@ 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). `-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`. Per ambienti condivisi o di produzione, usare un certificato CA valida e rimuovere `-SkipCACheck`.
Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md). Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md).
Setup-Host.ps1
+2 -2
View File
@@ -339,7 +339,7 @@ Write-Host " $CIRoot\ISO\"
Write-Host "" Write-Host ""
Write-Host " 3. Provision the template VM:" Write-Host " 3. Provision the template VM:"
Write-Host " a. Create VM in VMware Workstation (4 vCPU, 6 GB RAM, 80 GB thin)" Write-Host " a. Create VM in VMware Workstation (4 vCPU, 6 GB RAM, 80 GB thin)"
Write-Host " VMX: $CIRoot\Templates\WinBuild\WinBuild2025.vmx" Write-Host " VMX: $CIRoot\Templates\WinBuild2025\WinBuild2025.vmx"
Write-Host " NIC: VMnet8 (NAT) — internet required during provisioning" Write-Host " NIC: VMnet8 (NAT) — internet required during provisioning"
Write-Host " b. Install Windows Server 2025 + enable WinRM inside VM" Write-Host " b. Install Windows Server 2025 + enable WinRM inside VM"
Write-Host " c. From this host run:" Write-Host " c. From this host run:"
@@ -354,4 +354,4 @@ Write-Host ""
Write-Host " 5. Verify act_runner is Online in Gitea:" Write-Host " 5. Verify act_runner is Online in Gitea:"
Write-Host " $GiteaUrl/-/admin/runners" Write-Host " $GiteaUrl/-/admin/runners"
Write-Host "" Write-Host ""
TODO.md
+15 -15
View File
@@ -31,12 +31,12 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
| [ ] | Gitea Workflow Integration | 4 | 1 | manca solo §P3 generalizzazione workflow | | [ ] | Gitea Workflow Integration | 4 | 1 | manca solo §P3 generalizzazione workflow |
| [x] | §1 Sicurezza & hardening | 3 | 0 | 1.1, 1.4, 1.6 done; 1.2/1.3/1.5/1.7/1.8 deferred (home lab) | | [x] | §1 Sicurezza & hardening | 3 | 0 | 1.1, 1.4, 1.6 done; 1.2/1.3/1.5/1.7/1.8 deferred (home lab) |
| [x] | §2 Affidabilità & resilienza | 7 | 0 | tutto done (2.1-2.7) | | [x] | §2 Affidabilità & resilienza | 7 | 0 | tutto done (2.1-2.7) |
| [x] | §3 Performance & throughput | 4 | 0 | 3.1/3.2/3.3/3.6 done; 3.4/3.5 deferred — **§3 CHIUSO** | | [x] | §3 Performance & throughput | 4 | 0 | 3.1/3.2/3.3/3.6 done; 3.4/3.5 deferred — **§3 CHIUSO** |
| [x] | §4 Osservabilità & manutenzione | 3 | 0 | 4.1/4.3/4.4 done (4.2 Prometheus, 4.5 Dashboard rimossi) | | [x] | §4 Osservabilità & manutenzione | 3 | 0 | 4.1/4.3/4.4 done (4.2 Prometheus, 4.5 Dashboard rimossi) |
| [x] | §5 Qualità codice & test | 5 | 0 | 5.1/5.2/5.3/5.4/5.5 done | | [x] | §5 Qualità codice & test | 5 | 0 | 5.1/5.2/5.3/5.4/5.5 done |
| [ ] | §6 Scalabilità & estensioni | 1 | 5 | 6.6 Tier-1 (Git+7-Zip) done; 6.1 (Linux), 6.2-6.5 TODO | | [ ] | §6 Scalabilità & estensioni | 1 | 5 | 6.6 Tier-1 (Git+7-Zip) done; 6.1 (Linux), 6.2-6.5 TODO |
| [ ] | §7 Refactor Deploy ↔ Setup | 4 | 1 | 7.1/7.2/7.3/7.4 done; 7.5 (rinomina) opzionale | | [ ] | §7 Refactor Deploy ↔ Setup | 4 | 1 | 7.1/7.2/7.3/7.4 done; 7.5 (rinomina) opzionale |
| [x] | In-VM Git Clone (§3.3) | 4 | 0 | COMPLETATO 2026-05-10 — e2e PASS: 34s/25.7% vs baseline | | [x] | In-VM Git Clone (§3.3) | 4 | 0 | COMPLETATO 2026-05-10 — e2e PASS: 34s/25.7% vs baseline |
| [ ] | Linux Build VM (§6.1) | 0 | 4 | bozza in `docs/LINUX-TEMPLATE-SETUP.md` | | [ ] | Linux Build VM (§6.1) | 0 | 4 | bozza in `docs/LINUX-TEMPLATE-SETUP.md` |
**Prossimi passi consigliati** (vedi anche "Suggerimento di sequencing" in fondo): **Prossimi passi consigliati** (vedi anche "Suggerimento di sequencing" in fondo):
@@ -69,7 +69,7 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
- [x] `F:\CI\act_runner\` - [x] `F:\CI\act_runner\`
- [x] `F:\CI\Cache\NuGet\` - [x] `F:\CI\Cache\NuGet\`
- [x] `F:\CI\RunnerWork\` - [x] `F:\CI\RunnerWork\`
- [x] `F:\CI\Templates\WinBuild\` - [x] `F:\CI\Templates\WinBuild2025\`
- [x] `F:\CI\Logs\` — log per job (retention: 30 giorni) - [x] `F:\CI\Logs\` — log per job (retention: 30 giorni)
- [x] `F:\CI\ISO\` — contiene `26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso` (Windows Server 2025) - [x] `F:\CI\ISO\` — contiene `26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso` (Windows Server 2025)
@@ -84,7 +84,7 @@ _Last updated: 2026-05-10 (post Sprint 8: §3.3 e2e PASS — 34s/25.7% faster,
### Fase A — Crea e installa la VM (NIC: NAT per internet) ### Fase A — Crea e installa la VM (NIC: NAT per internet)
- [x] Crea nuova VM in VMware Workstation con queste impostazioni: - [x] Crea nuova VM in VMware Workstation con queste impostazioni:
- 4 vCPU, 6144 MB RAM, disco 80 GB thin - 4 vCPU, 6144 MB RAM, disco 80 GB thin
- VMX path: `F:\CI\Templates\WinBuild\WinBuild2025.vmx` - VMX path: `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
- **NIC: VMnet8 (NAT)** ← internet necessario per Windows Update e installer - **NIC: VMnet8 (NAT)** ← internet necessario per Windows Update e installer
- CD-ROM: `F:\CI\ISO\26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso` - CD-ROM: `F:\CI\ISO\26100.1742.240906-0331.ge_release_svc_refresh_SERVER_VOL_x64FRE_en-us.iso`
- [x] Installa Windows Server 2025 dall'ISO - [x] Installa Windows Server 2025 dall'ISO
@@ -516,18 +516,18 @@ build più ampi senza toccare il template.
### Tier-2 (backlog) — tool da aggiungere come ulteriori step `Setup-WinBuild2025` (ognuno con `Assert-Step`): ### Tier-2 (backlog) — tool da aggiungere come ulteriori step `Setup-WinBuild2025` (ognuno con `Assert-Step`):
| Tool | Versione | Razionale | | Tool | Versione | Razionale |
| ------------------- | ----------------------- | -------------------------------------------------------------- | | ------------------- | ----------------------- | ------------------------------------------------------------------ |
| **Git for Windows** | 2.54.0.windows.1 | [x] Self-clone in VM (alt a host-zip-transfer), submodule fetch | | **Git for Windows** | 2.54.0.windows.1 | [x] Self-clone in VM (alt a host-zip-transfer), submodule fetch |
| **7-Zip** | 26.01 | [x] Universale unpack/zip; molti installer e workflow ne dipendono | | **7-Zip** | 26.01 | [x] Universale unpack/zip; molti installer e workflow ne dipendono |
| **PowerShell 7.x** | latest LTS | [ ] Più veloce di 5.1, parallel pipelines, operatori moderni | | **PowerShell 7.x** | latest LTS | [ ] Più veloce di 5.1, parallel pipelines, operatori moderni |
| **NSIS** | latest | Test build installer (es. `nsis-plugin-nsinnounp`) | | **NSIS** | latest | Test build installer (es. `nsis-plugin-nsinnounp`) |
| **CMake** | latest | Build system cross-platform per progetti C/C++ nativi | | **CMake** | latest | Build system cross-platform per progetti C/C++ nativi |
| **Node.js LTS** | latest LTS | Frontend/Electron pipelines, JS toolchain (npm) | | **Node.js LTS** | latest LTS | Frontend/Electron pipelines, JS toolchain (npm) |
| **WiX Toolset** | v4 stable | MSI building da .NET projects | | **WiX Toolset** | v4 stable | MSI building da .NET projects |
| **gh CLI** | latest | Upload artifact a release Gitea/GitHub, comment PR | | **gh CLI** | latest | Upload artifact a release Gitea/GitHub, comment PR |
| **Sysinternals** | sysinternals.com `live` | Diagnostica process/handle quando build flaky | | **Sysinternals** | sysinternals.com `live` | Diagnostica process/handle quando build flaky |
| **vcpkg** | latest | Package manager C++ per dipendenze native | | **vcpkg** | latest | Package manager C++ per dipendenze native |
**Approccio**: **Approccio**:
- Pinning hash SHA256 per ogni installer (vedi §1.3) - Pinning hash SHA256 per ogni installer (vedi §1.3)
@@ -806,7 +806,7 @@ alla successiva.
| act_runner | `F:\CI\act_runner\act_runner.exe` (servizio: `act_runner`) | | act_runner | `F:\CI\act_runner\act_runner.exe` (servizio: `act_runner`) |
| act_runner config | `F:\CI\act_runner\config.yaml` | | act_runner config | `F:\CI\act_runner\config.yaml` |
| act_runner logs | `F:\CI\act_runner\logs\` | | act_runner logs | `F:\CI\act_runner\logs\` |
| Template VMX | `F:\CI\Templates\WinBuild\WinBuild2025.vmx` | | Template VMX | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` |
| Snapshot name | `BaseClean` | | Snapshot name | `BaseClean` |
| Clone base dir | `F:\CI\BuildVMs\` | | Clone base dir | `F:\CI\BuildVMs\` |
| Artifact dir | `F:\CI\Artifacts\` | | Artifact dir | `F:\CI\Artifacts\` |
docs/ARCHITECTURE.md
+3 -2
View File
@@ -117,7 +117,7 @@ The runner host **never executes build tools directly**. Its only role is orches
- .NET SDK **10.0.203** - .NET SDK **10.0.203**
- Python **3.13.3** (per build script personalizzati come `build_plugin.py`) - Python **3.13.3** (per build script personalizzati come `build_plugin.py`)
- NuGet CLI (optional, dotnet restore covers most cases) - NuGet CLI (optional, dotnet restore covers most cases)
- Git: NOT installed by default — source arrives via WinRM zip transfer. See TODO.md `-UseGitClone` for the in-VM git clone opt-in path. - **Git for Windows 2.54** + **7-Zip 26.01** (Tier-1 toolchain, §6.6 — DONE 2026-05-10): consente l'opt-in `-UseGitClone` di `Invoke-CIJob.ps1` per clonare il repository direttamente in VM (skip host zip transfer, e2e PASS, -25.7% durata pipeline).
--- ---
@@ -191,4 +191,5 @@ VMs have internet access via NAT — required for pip/nuget during build.
- WinRM credentials are stored in Windows Credential Manager on host (not hardcoded) - WinRM credentials are stored in Windows Credential Manager on host (not hardcoded)
- Each VM is fully destroyed after the job — no state carries between builds - Each VM is fully destroyed after the job — no state carries between builds
- Runner host does not expose any ports to the build VM network - Runner host does not expose any ports to the build VM network
- Source code is transferred via zip (Compress-Archive → WinRM copy → Expand-Archive in guest) — no PAT is ever present inside the VM; VMs have NAT internet for pip/nuget at build time - Source code is transferred via zip (Compress-Archive → WinRM copy → Expand-Archive in guest) by default — no PAT is ever present inside the VM; VMs have NAT internet for pip/nuget at build time.
- With `-UseGitClone` (§3.3, opt-in) il clone avviene dentro la VM via SSH alias `gitea-ci` (forwardato dall'host); la chiave privata SSH dell'host non viene esposta al guest — vedi BEST-PRACTICES.md per il threat model.
docs/CI-FLOW.md
+5 -2
View File
@@ -138,8 +138,11 @@ Sequence inside the PSSession:
``` ```
1. New-PSSession → open WinRM session to VM 1. New-PSSession → open WinRM session to VM
2. Compress-Archive (host) → copy zip to C:\CI\build.zip (guest) → Expand-Archive to C:\CI\build\ 2a. (default) Compress-Archive (host) → copy zip to C:\CI\build.zip (guest) → Expand-Archive to C:\CI\build\
(source code è già clonato sull'host in Phase 1 — non si fa git clone nella VM) (source code è già clonato sull'host in Phase 1 — nessun git clone nella VM)
2b. (opt-in, `-UseGitClone`, §3.3 DONE 2026-05-10)
git clone direttamente in VM tramite `ssh://gitea-ci/...` (richiede Git+7-Zip in template, §6.6 Tier-1)
Vantaggio: skip host-zip-transfer, -25.7% durata pipeline (e2e PASS). Verifica SHA commit post-clone.
3. Invoke-Expression "$BuildCommand" in C:\CI\build\ 3. Invoke-Expression "$BuildCommand" in C:\CI\build\
Esempio: python build_plugin.py --final --dist-dir dist Esempio: python build_plugin.py --final --dist-dir dist
a. Build 4 configurazioni MSBuild in parallelo (x86-unicode, x64-unicode, cli-x86, cli-x64) a. Build 4 configurazioni MSBuild in parallelo (x86-unicode, x64-unicode, cli-x86, cli-x64)
docs/HOST-SETUP.md
+8 -8
View File
@@ -33,13 +33,13 @@ F:\CI\
├── Artifacts\ # output build raccolti dall'host ├── Artifacts\ # output build raccolti dall'host
├── Logs\ # log per-job (retention: 30 giorni) ├── Logs\ # log per-job (retention: 30 giorni)
├── Templates\ ├── Templates\
│ └── WinBuild\ # VMX template Windows (immutabile dopo snapshot) │ └── WinBuild2025\ # VMX template Windows (immutabile dopo snapshot)
├── act_runner\ ├── act_runner\
│ ├── act_runner.exe # binario runner Gitea │ ├── act_runner.exe # binario runner Gitea
│ ├── config.yaml # config runner (path, label, capacity) │ ├── config.yaml # config runner (path, label, capacity)
│ └── logs\ # stdout/stderr del servizio │ └── logs\ # stdout/stderr del servizio
├── Cache\ ├── Cache\
│ └── NuGet\ # cache NuGet condivisa via shared folder (TODO §3.1) │ └── NuGet\ # cache NuGet condivisa via shared folder (§3.1 — DONE 2026-05-10, vedi scripts/Set-TemplateSharedFolders.ps1)
├── RunnerWork\ # working dir di act_runner (job staging) ├── RunnerWork\ # working dir di act_runner (job staging)
└── ISO\ # ISO di installazione (Windows Server 2025, ecc.) └── ISO\ # ISO di installazione (Windows Server 2025, ecc.)
``` ```
@@ -161,13 +161,13 @@ Allo `Setup-Host.ps1` exit 0:
## Maintenance & operational tasks ## Maintenance & operational tasks
Voci di backlog (vedi [TODO.md](../TODO.md)): Task schedulati (vedi `scripts/Register-CIScheduledTasks.ps1` per il bootstrap):
- **§2.2** Cleanup VM orfane schedulato (`scripts/Cleanup-OrphanedBuildVMs.ps1` ogni 6h, `-MaxAgeHours 4`) - **§2.2** Cleanup VM orfane (`scripts/Cleanup-OrphanedBuildVMs.ps1`, ogni 6h, `-MaxAgeHours 4`)
- **§2.3** Retention artifact + log (Artifacts > 30 gg, Logs > 30 gg, guard libero < 50 GB) - **§2.3** Retention artifact + log (`scripts/Invoke-RetentionPolicy.ps1`, daily)
- **§2.7** Health check runner (query API Gitea ogni 15 min, restart su offline) - **§2.6** Backup template (`scripts/Backup-CITemplate.ps1`, weekly)
- **§4.3** Disk space alert (`F:` < 50 GB → eventcreate/webhook) - **§2.7** Health check runner (`scripts/Watch-RunnerHealth.ps1`, ogni 15 min)
- **§1.2** Restringere `TrustedHosts` da `*` a `192.168.79.*` - **§4.3** Disk space alert (`scripts/Watch-DiskSpace.ps1`, ogni ora)
--- ---
docs/OPTIMIZATION.md
+1 -1
View File
@@ -104,7 +104,7 @@ F:\CI\Cache\NuGet\ ← shared folder on host
### VMware Shared Folder Configuration (in template VMX) ### VMware Shared Folder Configuration (in template VMX)
Add to `WinBuild.vmx` before taking the `BaseClean` snapshot: Add to `WinBuild2025.vmx` before taking the `BaseClean` snapshot:
```ini ```ini
sharedFolder0.present = "TRUE" sharedFolder0.present = "TRUE"
sharedFolder0.enabled = "TRUE" sharedFolder0.enabled = "TRUE"
docs/archived/2026-05-10/Setup-GiteaSSH.md → docs/Setup-GiteaSSH.md
View File
docs/TEST-PLAN-v1.3-to-HEAD.md
+8 -8
View File
@@ -7,14 +7,14 @@ Organized by sprint area with pre-requisites, test steps, and pass/fail criteria
## Overview ## Overview
| Area | Items | Status | Baseline | | Area | Items | Status | Baseline |
| ----------------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------- | | ----------------------------- | ----------------------- | -------- | ------------------------------------------------------------------------- |
| **Sprint 2** (Reliability) | 2.1/2.2/2.3/2.5 | Partial | §2.2/§2.3 validated locally 2026-05-10; §2.1/§2.5 need real VMs | | **Sprint 2** (Reliability) | 2.1/2.2/2.3/2.5 | Partial | §2.2/§2.3 validated locally 2026-05-10; §2.1/§2.5 need real VMs |
| **Sprint 3** (Observability) | 4.1/4.3/4.4 | Partial | §4.3/§4.4 validated locally 2026-05-10; §4.1 (JSONL) needs real build job | | **Sprint 3** (Observability) | 4.1/4.3/4.4 | Partial | §4.3/§4.4 validated locally 2026-05-10; §4.1 (JSONL) needs real build job |
| **Sprint 4-6** (Quality/Perf) | 1.4/3.1/3.6/5.2/5.3/5.4 | Partial | §1.4/§5.2/§5.3/§5.4 validated 2026-05-10; §3.1/§3.6 need real VMs | | **Sprint 4-6** (Quality/Perf) | 1.4/3.1/3.6/5.2/5.3/5.4 | Partial | §1.4/§5.2/§5.3/§5.4 validated 2026-05-10; §3.1/§3.6 need real VMs |
| **Sprint 7** (Testing) | 5.1 | [x] Done | 22/22 Pester tests passing in 12.9s (2026-05-10) | | **Sprint 7** (Testing) | 5.1 | [x] Done | 22/22 Pester tests passing in 12.9s (2026-05-10) |
| **§1.6** (Docs) | Threat model | [x] Done | BEST-PRACTICES.md verified 2026-05-10 | | **§1.6** (Docs) | Threat model | [x] Done | BEST-PRACTICES.md verified 2026-05-10 |
| **§3.2** (Perf) | 7-Zip compression | Partial | Fallback path validated; in-VM 7-Zip speed test needs real VM | | **§3.2** (Perf) | 7-Zip compression | Partial | Fallback path validated; in-VM 7-Zip speed test needs real VM |
--- ---
docs/WINDOWS-TEMPLATE-SETUP.md
+3 -3
View File
@@ -37,7 +37,7 @@ credenziali archiviate, ISO Windows Server presente).
| RAM | 6144 MB (6 GB) | | RAM | 6144 MB (6 GB) |
| Disco | 80 GB thin provisioned | | Disco | 80 GB thin provisioned |
| NIC | **VMnet8 (NAT)** — internet richiesto per WU + installer | | NIC | **VMnet8 (NAT)** — internet richiesto per WU + installer |
| VMX path | `F:\CI\Templates\WinBuild\WinBuild2025.vmx` | | VMX path | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` |
| ISO | Windows Server 2025 (da `F:\CI\ISO\`) | | ISO | Windows Server 2025 (da `F:\CI\ISO\`) |
--- ---
@@ -48,7 +48,7 @@ credenziali archiviate, ISO Windows Server presente).
- File → New Virtual Machine → Custom - File → New Virtual Machine → Custom
- Hardware: 4 vCPU, 6144 MB, 80 GB thin - Hardware: 4 vCPU, 6144 MB, 80 GB thin
- Network: **VMnet8 (NAT)** - Network: **VMnet8 (NAT)**
- VMX: `F:\CI\Templates\WinBuild\WinBuild2025.vmx` - VMX: `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
- CD/DVD: monta ISO Windows Server 2025 - CD/DVD: monta ISO Windows Server 2025
### A.2 Installa Windows Server 2025 ### A.2 Installa Windows Server 2025
@@ -219,7 +219,7 @@ Final Pre-snapshot gate — 7 check cross-cutting + no installer leftover
- VM → Snapshot → Take Snapshot - VM → Snapshot → Take Snapshot
- **Nome esatto: `BaseClean`** (case-sensitive, usato da `New-BuildVM.ps1`) - **Nome esatto: `BaseClean`** (case-sensitive, usato da `New-BuildVM.ps1`)
3. **Lascia la VM spenta** — non modificarla mai più dopo lo snapshot 3. **Lascia la VM spenta** — non modificarla mai più dopo lo snapshot
4. **Verifica `runner/config.yaml`**: `GITEA_CI_TEMPLATE_PATH=F:\CI\Templates\WinBuild\WinBuild2025.vmx` 4. **Verifica `runner/config.yaml`**: `GITEA_CI_TEMPLATE_PATH=F:\CI\Templates\WinBuild2025\WinBuild2025.vmx`
--- ---
PLAN.md → docs/archived/2026-05-10/PLAN.md
View File
docs/archived/2026-05-10/README.md
+18 -4
View File
@@ -4,9 +4,15 @@ Date: 2026-05-10
## Archived Files ## Archived Files
### Setup-GiteaSSH.md ### PLAN.md (archived 2026-05-10)
**Reason**: Obsolete — current workflow uses HTTP URLs + credential manager for Gitea access, not SSH key-based authentication. **Reason**: Pianificazione iniziale (ultimo update 2026-05-08) superata dallo stato post Sprint 8.
**When to revisit**: If SSH-based Git clones become necessary (e.g., for server-to-server scenarios). Stato corrente del sistema, decisioni tecniche e roadmap sono ora distribuiti tra:
- `TODO.md` (root) per audit trail, summary status e backlog
- `docs/ARCHITECTURE.md` per il design del sistema
- `docs/CI-FLOW.md` per il flusso operativo
- `docs/RUNBOOK.md` per il triage incident
Resta come riferimento storico.
### TEST-7.4-e2e.md ### TEST-7.4-e2e.md
**Reason**: Sprint 7.4 refactor validation document. Specific to §7.4 Deploy↔Setup refactor completion testing. **Reason**: Sprint 7.4 refactor validation document. Specific to §7.4 Deploy↔Setup refactor completion testing.
@@ -16,6 +22,13 @@ Date: 2026-05-10
- Post-refactor sign-off checklist - Post-refactor sign-off checklist
**Useful for**: §6.6 (Toolchain Tier-1) template updates, Linux template setup (§6.1) **Useful for**: §6.6 (Toolchain Tier-1) template updates, Linux template setup (§6.1)
## De-archived
### Setup-GiteaSSH.md (restored 2026-05-10)
Originariamente archiviato come "obsolete (HTTP+credential manager)" ma di fatto il workflow
live (`gitea/workflows/build-nsis.yml`) e `Setup-Host.ps1` continuano a usare l'alias SSH
`gitea-ci` (porta 2222) per i clone Git. Ripristinato in `docs/Setup-GiteaSSH.md`.
## Active Documentation ## Active Documentation
All current, operational docs remain in parent directory: All current, operational docs remain in parent directory:
@@ -24,7 +37,8 @@ All current, operational docs remain in parent directory:
- CI-FLOW.md - CI-FLOW.md
- HOST-SETUP.md - HOST-SETUP.md
- WINDOWS-TEMPLATE-SETUP.md - WINDOWS-TEMPLATE-SETUP.md
- LINUX-TEMPLATE-SETUP.md (draft for §6.1)
- OPTIMIZATION.md - OPTIMIZATION.md
- RUNBOOK.md - RUNBOOK.md
- TEST-PLAN-v1.3-to-HEAD.md - TEST-PLAN-v1.3-to-HEAD.md
- LINUX-TEMPLATE-SETUP.md (draft for §6.1) - Setup-GiteaSSH.md