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
parent a60f7a4b90
commit 90a4396443
12 changed files with 114 additions and 64 deletions
@@ -2,7 +2,7 @@

 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 |
 |---|---|
 | 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) |
 | .NET SDK | 10.0.203 |
 | 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
+├── PSScriptAnalyzerSettings.psd1 # Regole linting condivise (§5.4)
 │
 ├── 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
-│   ├── Wait-VMReady.ps1          # Polling WinRM readiness
-│   ├── Invoke-RemoteBuild.ps1    # Zip transfer + esecuzione build in VM
+│   ├── 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
+│   ├── 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/
-│   ├── Prepare-WinBuild2025.ps1 # Provisioning automatico template VM (HOST-side)
-│   └── Setup-WinBuild2025.ps1    # Installazione toolchain nella VM (GUEST-side)
+│   ├── 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
+│   │   ├── 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)
+│   ├── 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
-│   └── Setup-GiteaSSH.md         # Configurazione SSH alias per Gitea
+│   ├── 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
 │
-├── PLAN.md                       # Stato implementazione e decisioni tecniche
-└── TODO.md                       # Task completati e roadmap futura
+└── TODO.md                       # Roadmap, audit trail task completati, backlog
 ```

 ---
@@ -131,10 +153,12 @@ 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, 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'
 ```

-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/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/BEST-PRACTICES.md](docs/BEST-PRACTICES.md) | Sicurezza WinRM, gestione credenziali, isolamento |
+| [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 |

 ---

@@ -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).
 Per ambienti condivisi o di produzione, usare un certificato CA valida e rimuovere `-SkipCACheck`.
 Vedi [docs/BEST-PRACTICES.md](docs/BEST-PRACTICES.md).
-
+