local-ci-cd-system/docs/LIFECYCLE.md

CI/CD Job Lifecycle

flowchart TD
    A([git push]) --> B[Gitea Actions\ntrigger workflow]
    B --> C[act_runner\nWindows service]
    C --> D["python -m ci_orchestrator job\njob.py · job()"]

    D --> SRC{use-git-clone?}

    SRC -->|false — default| HOST_CLONE["host: git clone\n+ Compress-Archive\n+ WinRM copy zip\n+ Expand-Archive in VM"]
    SRC -->|true — opt-in| VM_CLONE["skip host clone\nVM: git clone --recurse-submodules\nhttps://PAT@gitea/repo\n~25.7% faster"]

    HOST_CLONE --> E
    VM_CLONE --> E

    D --> LB
    LB --> E

    E["vm_new()\nlinked clone from template snapshot"]
    E --> F{guestOS in VMX?}

    F -->|ubuntu-*| G_WAIT["wait_ready()\nSSH poll · port 22"]
    F -->|Windows| W_WAIT["wait_ready()\nWinRM poll · port 5986"]

    G_WAIT --> G_PROBE["_probe_transport()\nSshTransport"]
    W_WAIT --> W_PROBE["_probe_transport()\nWinRmTransport"]

    G_PROBE --> G_BUILD["_linux_build()\nSSH + SFTP · paramiko"]
    W_PROBE --> W_BUILD["_windows_build()\nWinRM · pypsrp"]

    G_BUILD --> G_ART["_linux_collect()\nSCP artifacts"]
    W_BUILD --> W_ART["_windows_collect()\nWinRM Copy-Item"]

    G_ART --> DESTROY
    W_ART --> DESTROY

    DESTROY["_destroy_clone()\nvmrun stop + deleteVM"]
    DESTROY --> DONE([Job complete])

    subgraph Templates
        T1["WinBuild2025\nBaseClean · WinRM"]
        T2["WinBuild2022\nBaseClean · WinRM"]
        T3["LinuxBuild2404\nBaseClean-Linux · SSH"]
    end

    E -.->|clone from| T1
    E -.->|clone from| T2
    E -.->|clone from| T3

    subgraph Backend
        LB["load_backend()\nWorkstationVmrunBackend\nwraps vmrun.exe"]
    end

Phase breakdown

Phase	Module	Transport
Clone VM	commands/vm.py · vm_new()	vmrun.exe (host)
Source delivery	workflow input use-git-clone	WinRM (in-VM git clone) or host zip
Wait ready	commands/wait.py · wait_ready()	SSH/22 or WinRM/5986
Build	commands/build.py · build_run()	paramiko (Linux) / pypsrp (Windows)
Collect artifacts	commands/artifacts.py · artifacts_collect()	SCP (Linux) / WinRM Copy-Item (Windows)
Destroy VM	commands/job.py · _destroy_clone()	vmrun.exe (host)

Transport selection

job.py reads guestOS from the cloned .vmx:

• ubuntu-* → SshTransport (paramiko, key auth, ci_build user)
• anything else → WinRmTransport (pypsrp, HTTPS/5986)

Source delivery modes

Mode	Trigger	Flow	Notes
Standard	use-git-clone: false (default)	host clone → zip → WinRM copy → expand	No credentials in VM
UseGitClone	use-git-clone: true	VM clones directly via PAT	25.7% faster, PAT never persisted