Align N2K release checkout source

Author: dhslove

.github/workflows/build.yml

@@ -22,6 +22,9 @@ permissions:
   contents: write
   actions: read
 
+env:
+  WORKFLOW_SOURCE_REF: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.ref }}
+
 # NOTE (WinPE ISO)
 # - WinPE ISO artifacts are produced by the dedicated WinPE release workflows.
 # - This workflow optionally downloads the released WinPE ISO and bundles it into the final release artifacts.
@@ -40,6 +43,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install build deps (Rocky 9.6 vault)
         run: |
@@ -102,6 +106,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install build deps (hangctl, Rocky 9.6 vault)
         run: |
@@ -207,6 +212,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install build deps (ftctl, Rocky 9.6 vault)
         run: |
@@ -275,6 +281,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install build deps (v2k, Rocky ${{ matrix.host_os_minor }})
         run: |
@@ -554,6 +561,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install build deps (n2k, Rocky ${{ matrix.host_os_minor }})
         shell: bash
@@ -639,6 +647,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install build deps
         run: |
@@ -721,6 +730,9 @@ jobs:
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Install WiX v4
         run: dotnet tool install --global wix --version 4.*
@@ -751,13 +763,14 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          ref: ${{ github.event.workflow_run.head_sha }}
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Checkout workflow_dispatch source
         if: ${{ github.event_name == 'workflow_dispatch' }}
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          ref: ${{ env.WORKFLOW_SOURCE_REF }}
 
       - name: Resolve release context
         shell: bash
@@ -1990,6 +2003,7 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ env.RELEASE_TAG }}
+          target_commitish: ${{ env.RELEASE_REF }}
           body_path: release_notes.md
           files: |
             release/upload-assets/*

docs/n2k/ablestack_n2k_cloud_cutover_start_policy_design.md

@@ -0,0 +1,38 @@
+# ABLESTACK-N2K Cloud Cutover Start Policy and Release Checkout Design
+
+## Background
+
+Cloud-managed N2K migrations use the same engine as the CLI wizard, but the Cloud agent wrapper previously forced Cloud target cutover to pass `--start`. The CLI already distinguishes the two target policies:
+
+- `--apply`: deploy/import the target VM and leave it stopped.
+- `--apply --start`: deploy/import the target VM and start it after cutover.
+
+This means a user can already request a stopped target VM from direct CLI or wizard mode, but the Cloud UI/API path could not express that preference.
+
+The release workflow also had inconsistent checkout behavior during tag-triggered release builds. The release job checked out `workflow_run.head_sha`, while build jobs used the default checkout ref. If the default branch differs from the tag commit, generated artifacts can be built from a different commit than the release metadata.
+
+## Design
+
+### Cloud cutover policy
+
+The Cloud API owns the user-facing choice and passes it to the host command as a boolean start policy. The KVM wrapper maps it to the engine flags:
+
+- `starttargetvm=true`: pass `--start` and keep the current default behavior.
+- `starttargetvm=false`: pass `--apply` only, so Cloud creates the target VM but leaves it stopped.
+
+CLI and wizard behavior remains unchanged. Existing wizard users can keep using `--apply` or `--start` directly.
+
+### Release workflow checkout policy
+
+All build jobs and the release job must check out the same source ref:
+
+- `workflow_run`: use `github.event.workflow_run.head_sha`.
+- `workflow_dispatch`: use `github.ref`.
+
+The final GitHub Release must also publish with `target_commitish` equal to the resolved checked-out commit.
+
+## Compatibility
+
+- Default behavior remains start-after-cutover for existing Cloud API/UI users.
+- Direct CLI and wizard mode keep their current semantics.
+- No database schema change is required.