Merge pull request #26 from dhslove/codex/n2k-cloud-preserve-mac

N2K Cloud MAC 보존 및 릴리즈 checkout 기준 정리

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.

lib/n2k/target_cloud.sh

@@ -225,18 +225,27 @@ n2k_cloud_target_source_deploy_params_json() {
         elif ($s | test("scsi|lsilogic|pvscsi|buslogic")) then "scsi"
         else "" end;
 
+    def source_mac($vm):
+      (($vm.nics // [])
+       | map(.mac // .macAddress // .mac_address // "")
+       | map((. // "") | tostring | ascii_downcase)
+       | map(select(test("^([0-9a-f]{2}:){5}[0-9a-f]{2}$")))
+       | first) // "";
+
     (.source.vm // {}) as $vm
     | (($vm.cpu // 0) | tonumber? // 0) as $cpu
     | (($vm.memory_mb // 0) | tonumber? // 0) as $memory_mb
     | ((.target.cloud.cpu_speed // "1000") | tostring) as $cpu_speed
     | (($vm.firmware // "") | tostring | ascii_downcase) as $firmware
     | (($vm.secure_boot // false) == true) as $secure_boot
+    | (source_mac($vm)) as $source_mac
     | (controller(.disks[0].controller.type // "")) as $root_controller
     | (controller((.disks[1:] // [] | map(.controller.type // "") | map(select((. | tostring | length) > 0)) | first) // "")) as $data_controller
     | {}
       + (if $cpu > 0 then {"details[0].cpuNumber": ($cpu | floor | tostring)} else {} end)
       + {"details[0].cpuSpeed": $cpu_speed}
       + (if $memory_mb > 0 then {"details[0].memory": ($memory_mb | floor | tostring)} else {} end)
+      + (if ($source_mac | length) > 0 then {macaddress:$source_mac} else {} end)
       + (if ($root_controller | length) > 0 then {"details[0].rootDiskController": $root_controller} else {} end)
       + (if ($data_controller | length) > 0 then {"details[0].dataDiskController": $data_controller} else {} end)
       + (