local-ci-cd-system/plans/PhaseA-user-checklist.md

Fase A — Checklist finale per l'utente

La Fase A è code-complete e pushata sul branch feature/python-rewrite-and-linux-migration. Restano solo le validazioni che richiedono accesso fisico all'host CI con VMware Workstation, snapshot template attivi e act_runner registrato.

Questo documento elenca i passi da eseguire in ordine, con checklist e comandi copiabili. Stop a primo errore: ogni passo è un gate per il successivo.

Tempo stimato totale: 1–2 ore (escluse build lunghe nel passo 5).

---

Passo 1 — Aggiornare il venv di produzione sull'host CI

Il codice nuovo va installato nel venv che act_runner usa (F:\CI\python\venv\).

• Aprire PowerShell come amministratore sull'host CI.

• Posizionarsi nella copia git aggiornata del repo (pull del branch feature/python-rewrite-and-linux-migration):

  cd <path-locale-repo>
  git fetch origin
  git checkout feature/python-rewrite-and-linux-migration
  git pull
  

• Installare il package nel venv di produzione (non editable):

  & 'F:\CI\python\venv\Scripts\python.exe' -m pip install .
  

  ⚠️ Non usare pip install -e . su questo host. act_runner gira come LocalSystem. Un install editable scrive un .pth verso la sorgente; se il cd era in una dir di lavoro di act_runner (F:\CI\RunnerWork\<hash>\hostexecutor, transitoria) o sul drive utente N: (non risolto da LocalSystem), il runner fallisce con No module named ci_orchestrator. L'install regolare copia il package in site-packages su F: (accessibile a LocalSystem). Conseguenza: ogni modifica al codice richiede di ri-eseguire pip install . — è uno step di deploy. Assicurarsi che il cd del passo precedente punti alla copia git reale del repo, non a una dir sotto F:\CI\RunnerWork.

• Smoke check rapido che la CLI risponda:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator --help
  

  Atteso: lista degli 11 sub-comandi (wait-ready, vm, build, artifacts, monitor, report, job).

---

Passo 2 — Riavviare act_runner

L'act_runner gira come servizio SYSTEM e legge runner/config.yaml all'avvio. La modifica di A4 (PYTHONIOENCODING=utf-8) ha effetto solo dopo restart.

• Trovare il servizio:

  Get-Service | Where-Object { $_.Name -like '*act*runner*' }
  

• Restart (sostituisci <NomeServizio> con quello trovato):

  Restart-Service -Name '<NomeServizio>'
  

• Verificare che sia partito:

  Get-Service -Name '<NomeServizio>'
  

  Atteso: Status = Running.

---

Passo 3 — Smoke wait-ready su VM Windows reale

PoC pendente da A1.

• Clonare manualmente un template Windows:

  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws clone `
    'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
    'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' `
    linked -snapshot=BaseClean -cloneName=smoke-win
  

• Avviare la VM:

  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws start 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' nogui
  

• Eseguire wait-ready:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready `
    --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' `
    --guest-os windows --timeout 180
  

  Atteso: exit code 0 entro 3 minuti.

• Cleanup VM di smoke:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove `
    --vmx 'F:\CI\BuildVMs\smoke-win\smoke-win.vmx' --force
  

---

Passo 4 — Smoke wait-ready su VM Linux reale

Stesso schema, template Linux. PoC pendente da A1.

• Clonare:

  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws clone `
    'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
    'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' `
    linked -snapshot=BaseClean-Linux -cloneName=smoke-linux
  

• Start + wait-ready:

  & 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe' `
    -T ws start 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' nogui
  
  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator wait-ready `
    --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' `
    --guest-os linux --timeout 180
  

  Atteso: exit code 0.

  Prerequisito scoperto: F:\CI\config.toml deve esistere con ssh_key_path impostato — altrimenti SSH fallisce con No authentication methods available. Creato durante questa validazione; vedi HOST-SETUP.md step 6.

• Cleanup:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm remove `
    --vmx 'F:\CI\BuildVMs\smoke-linux\smoke-linux.vmx' --force
  

---

Passo 5 — Smoke end-to-end pipeline (job)

Valida A3+A4 insieme: clone → wait → build → collect → cleanup.

• Lanciare un job sul template Windows con uno script trivial:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
    --template-path 'F:\CI\Templates\WinBuild2025\WinBuild2025.vmx' `
    --snapshot-name BaseClean `
    --job-id smoke-job-win `
    --repo-url 'http://10.10.20.11:3100/Simone/your-repo.git' `
    --branch main `
    --build-command 'echo hello > artifact.txt' `
    --guest-artifact-source 'artifact.txt' `
    --artifact-base-dir 'F:\CI\Artifacts\smoke-job-win'
  

  Atteso: exit code 0, file F:\CI\Artifacts\smoke-job-win\artifact.txt presente, VM smoke-job-win non più esistente in F:\CI\BuildVMs\ (cleanup garantito).

• Ripetere su Linux:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator job `
    --template-path 'F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx' `
    --snapshot-name BaseClean-Linux `
    --guest-os linux `
    --job-id smoke-job-linux `
    --repo-url 'http://10.10.20.11:3100/Simone/your-repo.git' `
    --branch main `
    --build-command 'echo hello > artifact.txt' `
    --guest-artifact-source 'artifact.txt' `
    --artifact-base-dir 'F:\CI\Artifacts\smoke-job-linux'
  

  Atteso: exit code 0, F:\CI\Artifacts\smoke-job-linux\smoke-job-linux\artifact.txt presente.

• Verificare assenza VM orfane:

  & 'F:\CI\python\venv\Scripts\python.exe' -m ci_orchestrator vm cleanup --what-if
  

  Atteso: nessun candidato.

---

Passo 6 — Workflow Gitea end-to-end

Validazione di A4 lato runner reale.

• Aprire la UI Gitea, repo local-ci-cd-system, branch feature/python-rewrite-and-linux-migration.

• [~] Triggerare manualmente i 3 workflow (Actions → Run workflow):

  • lint.yml → atteso PASS

  • self-test.yml → PASS — validati entrambi i transport (in-guest clone default + host-side clone+zip) su Win e Linux:

    Job	Transport	Esito
    smoke-windows	in-guest git clone	SUCCESS 26s
    smoke-linux	in-guest git clone	SUCCESS 51s
    smoke-windows-hostclone	host-side clone + zip	SUCCESS 28s
    smoke-linux-hostclone	host-side clone + zip	SUCCESS 46s

    Note: artifact github-free (no upload-artifact; file raw su F:\CI\Artifacts\<job>); use-git-clone/submodules default ON.

  • build-nsInnoUnp.yml matrix Win+Linux → atteso PASS, artifact pubblicato per entrambe le piattaforme.

• Se uno fallisce: scaricare i log dell'esecuzione, aprire issue in TODO.md con sha del workflow run e output errore.

---

Passo 7 — Burn-in capacità (4 job concorrenti)

Validazione finale di A5 (definizione di "fatto Fase A").

• Triggerare il workflow build-nsInnoUnp.yml 4 volte di seguito (oppure usare lo script scripts/Test-CapacityBurnIn.ps1 che ora delega via shim alla CLI Python job):

  .\scripts\Test-CapacityBurnIn.ps1 -Concurrency 4 -Rounds 10
  

• Misurare:

  • Tutti i 40 job (4 × 10) PASS
  • Zero VM orfane in F:\CI\BuildVMs\ a fine burn-in
  • Zero file lock orfani in F:\CI\BuildVMs\*.lock
  • Spazio disco libero non scende sotto la soglia di Watch-DiskSpace

---

Passo 8 — Benchmark wall-clock

Confronto Python vs PowerShell. Pendenza A4.

• Eseguire prima del merge:

  .\scripts\Measure-CIBenchmark.ps1
  

  Annotare il tempo medio per job.

• Confrontare con il baseline pre-Python (se disponibile in docs/OPTIMIZATION.md o in un commit precedente). Tolleranza target: ±10%.

• Se delta > 10%: aprire issue in TODO.md con dettagli per profiling. NON è bloccante per il merge della Fase A.

---

Passo 9 — Merge della Fase A in main

Solo dopo che i passi 3–7 sono tutti [x] PASS.

• Aprire PR su Gitea: feature/python-rewrite-and-linux-migration → main.
• Verificare diff atteso: ~20 file Python nuovi sotto src/ci_orchestrator/, ~10 shim PS in scripts/, doc in plans/A*-closeout.md, AGENTS.md/ARCHITECTURE.md/README.md aggiornati.
• Self-review della PR: nessun secret, nessun path hardcodato fuori da config.py, nessun .venv/ committato.
• Merge (squash sconsigliato — preserva la storia per-fase).
• Tag release: git tag v2.0.0-phaseA (o convenzione preferita).

---

Tracciamento globale

Passo	Descrizione	Stato
1	Aggiorna venv di produzione	[x]
2	Restart act_runner	[x]
3	Smoke wait-ready Windows	[x]
4	Smoke wait-ready Linux	[x]
5	Smoke job end-to-end (Win + Linux)	[x]
6	Workflow Gitea (lint + self-test + build)	[ ]
7	Burn-in 4 job × 10 round	[ ]
8	Benchmark wall-clock	[ ]
9	Merge PR e tag release	[ ]

Quando tutti i passi sono [x], la Fase A è definitivamente chiusa e si può aprire la Fase B (porting su host Linux).