# CI/CD Job Lifecycle

```mermaid
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 |