ci: split package, tag, and release workflows (#855)

.github/workflows/create-tag.yml

@@ -0,0 +1,108 @@
+name: NanoKVM Create Tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Numeric version to tag, e.g. 2.5.0
+        required: true
+        type: string
+      commit_sha:
+        description: Full commit SHA on main (empty uses latest main)
+        required: false
+        default: ''
+        type: string
+
+concurrency:
+  group: create-tag-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  create-tag:
+    name: Create annotated tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: main
+
+      - name: Validate target
+        id: target
+        env:
+          COMMIT_INPUT: ${{ inputs.commit_sha }}
+          VERSION_INPUT: ${{ inputs.version }}
+        run: |
+          VERSION="$VERSION_INPUT"
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::invalid version '$VERSION', expected MAJOR.MINOR.PATCH"
+            exit 1
+          fi
+
+          git fetch --force --tags origin main
+
+          if [ -n "$COMMIT_INPUT" ]; then
+            if ! echo "$COMMIT_INPUT" | grep -qE '^[0-9a-fA-F]{40}$'; then
+              echo "::error::commit_sha must be a full 40-character hexadecimal SHA"
+              exit 1
+            fi
+            TARGET_SHA=$(git rev-parse "${COMMIT_INPUT}^{commit}" 2>/dev/null) || {
+              echo "::error::commit '$COMMIT_INPUT' does not exist"
+              exit 1
+            }
+          else
+            TARGET_SHA=$(git rev-parse 'origin/main^{commit}')
+          fi
+
+          if ! git merge-base --is-ancestor "$TARGET_SHA" origin/main; then
+            echo "::error::commit '$TARGET_SHA' is not reachable from origin/main"
+            exit 1
+          fi
+
+          set +e
+          git ls-remote --exit-code --tags origin "refs/tags/$VERSION" >/dev/null
+          TAG_STATUS=$?
+          set -e
+          case "$TAG_STATUS" in
+            0)
+              echo "::error::tag '$VERSION' already exists"
+              exit 1
+              ;;
+            2) ;;
+            *)
+              echo "::error::failed to check whether tag '$VERSION' exists"
+              exit 1
+              ;;
+          esac
+
+          echo "sha=$TARGET_SHA" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        env:
+          TARGET_SHA: ${{ steps.target.outputs.sha }}
+          VERSION: ${{ steps.target.outputs.version }}
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git tag -a "$VERSION" "$TARGET_SHA" -m "Release $VERSION"
+          git push origin "refs/tags/$VERSION"
+          ./scripts/verify-release-tag.sh "$VERSION" "$TARGET_SHA" >/dev/null
+
+      - name: Summary
+        env:
+          TARGET_SHA: ${{ steps.target.outputs.sha }}
+          VERSION: ${{ steps.target.outputs.version }}
+        run: |
+          {
+            echo '### NanoKVM tag created'
+            echo
+            echo "- Tag: \`$VERSION\`"
+            echo "- Commit: \`$TARGET_SHA\`"
+            echo
+            echo 'No package, GitHub Release, or CDN object was created.'
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/package.yml

@@ -0,0 +1,291 @@
+name: NanoKVM Package
+
+# Builds nanokvm_<version>.tar.gz and the latest.json manifest that the
+# on-device updater consumes (server/service/application/). Pull requests get a
+# uniquely identified, short-lived test artifact. Release publication is a
+# separate, explicit workflow that calls this one for an existing tag.
+#
+# This workflow does NOT publish to cdn.sipeed.com. Uploading latest.json is what
+# actually offers the update to every device in the field, so that step stays
+# manual and deliberate.
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .github/workflows/create-tag.yml
+      - .github/workflows/package.yml
+      - .github/workflows/release.yml
+      - kvmapp/**
+      - scripts/**
+      - server/**
+      - support/**
+      - tools/nanokvm_update_edid/**
+      - web/**
+      - Makefile
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to package, e.g. 2.4.4
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      version:
+        description: Numeric version to package
+        required: true
+        type: string
+      ref:
+        description: Existing tag or commit to check out
+        required: true
+        type: string
+    outputs:
+      artifact_name:
+        description: Uploaded Actions artifact name
+        value: ${{ jobs.package.outputs.artifact_name }}
+      version:
+        description: Packaged version
+        value: ${{ jobs.package.outputs.version }}
+
+concurrency:
+  group: package-${{ github.event.pull_request.number || inputs.ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    outputs:
+      artifact_name: ${{ steps.version.outputs.artifact_name }}
+      version: ${{ steps.version.outputs.version }}
+    permissions:
+      contents: read
+      packages: read
+
+    steps:
+      - name: Checkout event ref
+        if: inputs.ref == ''
+        uses: actions/checkout@v4
+        with:
+          # package.sh derives SOURCE_DATE_EPOCH from the commit date.
+          fetch-depth: 0
+          # Build scripts from a pull request must not inherit checkout's token.
+          persist-credentials: false
+
+      - name: Checkout requested ref
+        if: inputs.ref != ''
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ inputs.ref }}
+
+      - name: Resolve version
+        id: version
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          INPUT_VERSION: ${{ inputs.version }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          BUILD_SHA=$(git rev-parse HEAD)
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            VERSION="0.${PR_NUMBER}.${GITHUB_RUN_NUMBER}"
+            SOURCE_SHA="$HEAD_SHA"
+          elif [ -n "$INPUT_VERSION" ]; then
+            VERSION="$INPUT_VERSION"
+            SOURCE_SHA="$BUILD_SHA"
+          else
+            VERSION="$REF_NAME"
+            SOURCE_SHA="$BUILD_SHA"
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::error::invalid version '$VERSION', expected MAJOR.MINOR.PATCH"
+            exit 1
+          fi
+          if [ -z "$SOURCE_SHA" ]; then
+            echo "::error::could not resolve source commit"
+            exit 1
+          fi
+          SHORT_SHA=$(printf '%s' "$SOURCE_SHA" | cut -c1-12)
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            ARTIFACT_NAME="nanokvm-pr-${PR_NUMBER}-${SHORT_SHA}-run-${GITHUB_RUN_ID}-attempt-${GITHUB_RUN_ATTEMPT}"
+          else
+            ARTIFACT_NAME="nanokvm-${VERSION}-${SHORT_SHA}-run-${GITHUB_RUN_ID}-attempt-${GITHUB_RUN_ATTEMPT}"
+          fi
+          {
+            echo "artifact_name=$ARTIFACT_NAME"
+            echo "build_sha=$BUILD_SHA"
+            echo "source_sha=$SOURCE_SHA"
+            echo "version=$VERSION"
+          } >> "$GITHUB_OUTPUT"
+          echo "Packaging version $VERSION as $ARTIFACT_NAME"
+
+      - name: Free up disk space
+        run: |
+          df -h /
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          df -h /
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Set up pnpm
+        run: npm install --global pnpm@11
+
+      - name: Build frontend
+        run: make web
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        env:
+          GHCR_USER: ${{ github.actor }}
+          GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ok=0
+          for attempt in 1 2 3; do
+            if printf '%s' "$GHCR_TOKEN" \
+                 | docker login ghcr.io -u "$GHCR_USER" --password-stdin; then
+              ok=1
+              break
+            fi
+            echo "login attempt $attempt failed, retrying in 15s"
+            sleep 15
+          done
+          if [ "$ok" -ne 1 ]; then
+            echo "::error::could not log in to ghcr.io after 3 attempts"
+            exit 1
+          fi
+
+      - name: Pull builder image
+        id: image
+        env:
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          # GHCR only accepts lowercase repository paths.
+          # shellcheck disable=SC2153 # OWNER is supplied through the step environment.
+          owner=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
+          IMAGE_REPO="ghcr.io/$owner/nanokvm-builder"
+          TAGGED_REF="${IMAGE_REPO}:latest"
+          ok=0
+          for attempt in 1 2 3; do
+            if docker pull "$TAGGED_REF"; then
+              ok=1
+              break
+            fi
+            echo "pull attempt $attempt failed, retrying in 15s"
+            sleep 15
+          done
+          if [ "$ok" -ne 1 ]; then
+            echo "::error::could not pull $TAGGED_REF - run the 'Builder Image' workflow first and ensure PR builds can pull it without credentials"
+            exit 1
+          fi
+          RESOLVED_REF=$(docker image inspect --format='{{index .RepoDigests 0}}' "$TAGGED_REF")
+          case "$RESOLVED_REF" in
+            "$IMAGE_REPO"@sha256:*) ;;
+            *)
+              echo "::error::could not resolve immutable digest for $TAGGED_REF (got '$RESOLVED_REF')"
+              exit 1
+              ;;
+          esac
+          echo "Pulled $RESOLVED_REF"
+          echo "ref=$RESOLVED_REF" >> "$GITHUB_OUTPUT"
+
+      - name: Build riscv64 artifacts
+        run: |
+          make release-build \
+            DOCKER_TTY= \
+            IMAGE_NAME="${{ steps.image.outputs.ref }}"
+
+      - name: Assemble package
+        run: make package VERSION="${{ steps.version.outputs.version }}"
+
+      - name: Compare against the published release
+        # Informational only: highlights what changed relative to what devices
+        # are currently running. Never blocks the build.
+        continue-on-error: true
+        run: |
+          ./scripts/compare-release.sh \
+            "build/release/nanokvm_${{ steps.version.outputs.version }}.tar.gz"
+
+      - name: Write build provenance
+        env:
+          ARTIFACT_NAME: ${{ steps.version.outputs.artifact_name }}
+          BUILDER_IMAGE: ${{ steps.image.outputs.ref }}
+          BUILD_SHA: ${{ steps.version.outputs.build_sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          SOURCE_SHA: ${{ steps.version.outputs.source_sha }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          TARBALL="build/release/nanokvm_${VERSION}.tar.gz"
+          TARBALL_NAME=$(basename "$TARBALL")
+          SHA256_HEX=$(sha256sum "$TARBALL" | cut -d' ' -f1)
+          SHA512_HEX=$(sha512sum "$TARBALL" | cut -d' ' -f1)
+          SHA512_BASE64=$(jq -er '.sha512 | select(type == "string" and length > 0)' \
+            build/release/latest.json)
+          ACTUAL_BASE64=$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)
+          if [ "$SHA512_BASE64" != "$ACTUAL_BASE64" ]; then
+            echo "::error::latest.json sha512 does not match $TARBALL"
+            exit 1
+          fi
+          printf '%s  %s\n' "$SHA256_HEX" "$TARBALL_NAME" > build/release/sha256.txt
+          {
+            echo "artifact=${ARTIFACT_NAME}"
+            echo "version=${VERSION}"
+            echo "event=${GITHUB_EVENT_NAME}"
+            echo "pull_request=${PR_NUMBER}"
+            echo "source_sha=${SOURCE_SHA}"
+            echo "build_sha=${BUILD_SHA}"
+            echo "builder_image=${BUILDER_IMAGE}"
+            echo "run_id=${GITHUB_RUN_ID}"
+            echo "run_attempt=${GITHUB_RUN_ATTEMPT}"
+            echo "run_url=https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+            echo "tarball=${TARBALL_NAME}"
+            echo "sha256_hex=${SHA256_HEX}"
+            echo "sha512_hex=${SHA512_HEX}"
+            echo "sha512_base64=${SHA512_BASE64}"
+          } > build/release/BUILD_INFO.txt
+
+      - name: Summary
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          {
+            if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
+              echo "> [!WARNING]"
+              echo "> PR TEST ONLY — DO NOT PUBLISH TO CDN"
+              echo
+            fi
+            echo "### nanokvm_${VERSION}.tar.gz"
+            echo
+            echo '```text'
+            cat build/release/BUILD_INFO.txt
+            echo '```'
+            echo
+            echo '```json'
+            cat build/release/latest.json
+            echo '```'
+            echo
+            if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
+              echo "Upload only the inner tarball through NanoKVM's manual offline update UI."
+            else
+              echo "Publishing to \`cdn.sipeed.com/nanokvm/\` is a separate manual step."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.version.outputs.artifact_name }}
+          path: |
+            build/release/nanokvm_${{ steps.version.outputs.version }}.tar.gz
+            build/release/latest.json
+            build/release/sha256.txt
+            build/release/BUILD_INFO.txt
+          if-no-files-found: error
+          retention-days: ${{ github.event_name == 'pull_request' && 7 || 90 }}

.github/workflows/release.yml

@@ -1,343 +1,244 @@
-name: NanoKVM Package
+name: NanoKVM Release
-
-# Builds nanokvm_<version>.tar.gz and the latest.json manifest that the
-# on-device updater consumes (server/service/application/). Pull requests get a
-# uniquely identified, short-lived test artifact; version tags also attach the
-# same package to a GitHub release.
-#
-# This workflow does NOT publish to cdn.sipeed.com. Uploading latest.json is what
-# actually offers the update to every device in the field, so that step stays
-# manual and deliberate.
 
 on:
-  pull_request:
-    branches:
-      - main
-    paths:
-      - .github/workflows/release.yml
-      - kvmapp/**
-      - scripts/**
-      - server/**
-      - support/**
-      - tools/nanokvm_update_edid/**
-      - web/**
-      - Makefile
-  push:
-    tags:
-      - '[0-9]+.[0-9]+.[0-9]+'
   workflow_dispatch:
     inputs:
-      version:
+      tag:
-        description: Version to package, e.g. 2.4.4
+        description: Existing numeric tag to release, e.g. 2.5.0
         required: true
         type: string
+      release_action:
+        description: Publish a release or promote a tested prerelease
+        required: true
+        type: choice
+        options:
+          - publish-prerelease
+          - publish-stable
+          - promote-stable
 
+# Latest is repository-global, so all Release changes must be serialized.
 concurrency:
-  group: package-${{ github.event.pull_request.number || github.ref }}
+  group: nanokvm-github-release
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: false
 
 jobs:
-  package:
+  validate:
-    name: Build package
+    name: Resolve release tag
     runs-on: ubuntu-latest
-    timeout-minutes: 180
+    permissions:
+      contents: read
     outputs:
-      artifact_name: ${{ steps.version.outputs.artifact_name }}
+      source_sha: ${{ steps.tag.outputs.source_sha }}
-      version: ${{ steps.version.outputs.version }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Verify tag
+        id: tag
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          SOURCE_SHA=$(./scripts/verify-release-tag.sh "$TAG")
+          echo "source_sha=$SOURCE_SHA" >> "$GITHUB_OUTPUT"
+
+  package:
+    name: Build tag package
+    needs: validate
+    if: inputs.release_action != 'promote-stable'
     permissions:
       contents: read
       packages: read
+    uses: ./.github/workflows/package.yml
+    with:
+      ref: ${{ needs.validate.outputs.source_sha }}
+      version: ${{ inputs.tag }}
 
-    steps:
+  publish:
-      - name: Checkout
+    name: Publish GitHub release
-        uses: actions/checkout@v4
+    needs:
-        with:
+      - validate
-          # package.sh derives SOURCE_DATE_EPOCH from the commit date.
+      - package
-          fetch-depth: 0
+    if: inputs.release_action != 'promote-stable'
-          # Build scripts from a pull request must not inherit checkout's token.
-          persist-credentials: false
-
-      - name: Resolve version
-        id: version
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          INPUT_VERSION: ${{ inputs.version }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          REF_NAME: ${{ github.ref_name }}
-        run: |
-          if [ "$EVENT_NAME" = "pull_request" ]; then
-            VERSION="0.${PR_NUMBER}.${GITHUB_RUN_NUMBER}"
-            SOURCE_SHA="$HEAD_SHA"
-          elif [ -n "$INPUT_VERSION" ]; then
-            VERSION="$INPUT_VERSION"
-            SOURCE_SHA="$GITHUB_SHA"
-          else
-            VERSION="$REF_NAME"
-            SOURCE_SHA="$GITHUB_SHA"
-          fi
-          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
-            echo "::error::invalid version '$VERSION', expected MAJOR.MINOR.PATCH"
-            exit 1
-          fi
-          if [ -z "$SOURCE_SHA" ]; then
-            echo "::error::could not resolve source commit"
-            exit 1
-          fi
-          SHORT_SHA=$(printf '%s' "$SOURCE_SHA" | cut -c1-12)
-          if [ "$EVENT_NAME" = "pull_request" ]; then
-            ARTIFACT_NAME="nanokvm-pr-${PR_NUMBER}-${SHORT_SHA}-run-${GITHUB_RUN_ID}-attempt-${GITHUB_RUN_ATTEMPT}"
-          else
-            ARTIFACT_NAME="nanokvm-${VERSION}-${SHORT_SHA}-run-${GITHUB_RUN_ID}-attempt-${GITHUB_RUN_ATTEMPT}"
-          fi
-          echo "artifact_name=$ARTIFACT_NAME" >> "$GITHUB_OUTPUT"
-          echo "source_sha=$SOURCE_SHA" >> "$GITHUB_OUTPUT"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Packaging version $VERSION as $ARTIFACT_NAME"
-
-      - name: Free up disk space
-        run: |
-          df -h /
-          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
-          df -h /
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-
-      - name: Set up pnpm
-        run: npm install --global pnpm@11
-
-      - name: Build frontend
-        run: make web
-
-      - name: Log in to GHCR
-        if: github.event_name != 'pull_request'
-        env:
-          GHCR_USER: ${{ github.actor }}
-          GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          ok=0
-          for attempt in 1 2 3; do
-            if printf '%s' "$GHCR_TOKEN" \
-                 | docker login ghcr.io -u "$GHCR_USER" --password-stdin; then
-              ok=1
-              break
-            fi
-            echo "login attempt $attempt failed, retrying in 15s"
-            sleep 15
-          done
-          if [ "$ok" -ne 1 ]; then
-            echo "::error::could not log in to ghcr.io after 3 attempts"
-            exit 1
-          fi
-
-      - name: Pull builder image
-        id: image
-        env:
-          OWNER: ${{ github.repository_owner }}
-        run: |
-          # GHCR only accepts lowercase repository paths.
-          owner=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
-          IMAGE_REPO="ghcr.io/$owner/nanokvm-builder"
-          TAGGED_REF="${IMAGE_REPO}:latest"
-          ok=0
-          for attempt in 1 2 3; do
-            if docker pull "$TAGGED_REF"; then
-              ok=1
-              break
-            fi
-            echo "pull attempt $attempt failed, retrying in 15s"
-            sleep 15
-          done
-          if [ "$ok" -ne 1 ]; then
-            echo "::error::could not pull $TAGGED_REF - run the 'Builder Image' workflow first and ensure PR builds can pull it without credentials"
-            exit 1
-          fi
-          RESOLVED_REF=$(docker image inspect --format='{{index .RepoDigests 0}}' "$TAGGED_REF")
-          case "$RESOLVED_REF" in
-            "$IMAGE_REPO"@sha256:*) ;;
-            *)
-              echo "::error::could not resolve immutable digest for $TAGGED_REF (got '$RESOLVED_REF')"
-              exit 1
-              ;;
-          esac
-          echo "Pulled $RESOLVED_REF"
-          echo "ref=$RESOLVED_REF" >> "$GITHUB_OUTPUT"
-
-      - name: Build riscv64 artifacts
-        run: |
-          make release-build \
-            DOCKER_TTY= \
-            IMAGE_NAME="${{ steps.image.outputs.ref }}"
-
-      - name: Assemble package
-        run: make package VERSION="${{ steps.version.outputs.version }}"
-
-      - name: Compare against the published release
-        # Informational only: highlights what changed relative to what devices
-        # are currently running. Never blocks the build.
-        continue-on-error: true
-        run: |
-          ./scripts/compare-release.sh \
-            "build/release/nanokvm_${{ steps.version.outputs.version }}.tar.gz"
-
-      - name: Write build provenance
-        env:
-          ARTIFACT_NAME: ${{ steps.version.outputs.artifact_name }}
-          BUILDER_IMAGE: ${{ steps.image.outputs.ref }}
-          BUILD_SHA: ${{ github.sha }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          SOURCE_SHA: ${{ steps.version.outputs.source_sha }}
-          VERSION: ${{ steps.version.outputs.version }}
-        run: |
-          TARBALL="build/release/nanokvm_${VERSION}.tar.gz"
-          TARBALL_NAME=$(basename "$TARBALL")
-          SHA256_HEX=$(sha256sum "$TARBALL" | cut -d' ' -f1)
-          SHA512_HEX=$(sha512sum "$TARBALL" | cut -d' ' -f1)
-          SHA512_BASE64=$(jq -er '.sha512 | select(type == "string" and length > 0)' \
-            build/release/latest.json)
-          ACTUAL_BASE64=$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)
-          if [ "$SHA512_BASE64" != "$ACTUAL_BASE64" ]; then
-            echo "::error::latest.json sha512 does not match $TARBALL"
-            exit 1
-          fi
-          printf '%s  %s\n' "$SHA256_HEX" "$TARBALL_NAME" > build/release/sha256.txt
-          {
-            echo "artifact=${ARTIFACT_NAME}"
-            echo "version=${VERSION}"
-            echo "event=${GITHUB_EVENT_NAME}"
-            echo "pull_request=${PR_NUMBER}"
-            echo "source_sha=${SOURCE_SHA}"
-            echo "build_sha=${BUILD_SHA}"
-            echo "builder_image=${BUILDER_IMAGE}"
-            echo "run_id=${GITHUB_RUN_ID}"
-            echo "run_attempt=${GITHUB_RUN_ATTEMPT}"
-            echo "run_url=https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
-            echo "tarball=${TARBALL_NAME}"
-            echo "sha256_hex=${SHA256_HEX}"
-            echo "sha512_hex=${SHA512_HEX}"
-            echo "sha512_base64=${SHA512_BASE64}"
-          } > build/release/BUILD_INFO.txt
-
-      - name: Summary
-        env:
-          VERSION: ${{ steps.version.outputs.version }}
-        run: |
-          {
-            if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
-              echo "> [!WARNING]"
-              echo "> PR TEST ONLY — DO NOT PUBLISH TO CDN"
-              echo
-            fi
-            echo "### nanokvm_${VERSION}.tar.gz"
-            echo
-            echo '```text'
-            cat build/release/BUILD_INFO.txt
-            echo '```'
-            echo
-            echo '```json'
-            cat build/release/latest.json
-            echo '```'
-            echo
-            if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
-              echo "Upload only the inner tarball through NanoKVM's manual offline update UI."
-            else
-              echo "Publishing to \`cdn.sipeed.com/nanokvm/\` is a separate manual step."
-            fi
-          } >> "$GITHUB_STEP_SUMMARY"
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ steps.version.outputs.artifact_name }}
-          path: |
-            build/release/nanokvm_${{ steps.version.outputs.version }}.tar.gz
-            build/release/latest.json
-            build/release/sha256.txt
-            build/release/BUILD_INFO.txt
-          if-no-files-found: error
-          retention-days: ${{ github.event_name == 'pull_request' && 7 || 90 }}
-
-  publish-release:
-    name: Attach package to GitHub release
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
-    needs: package
     runs-on: ubuntu-latest
     permissions:
       contents: write
 
     steps:
+      - name: Checkout release tooling
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
       - name: Download package artifact
         uses: actions/download-artifact@v4
         with:
           name: ${{ needs.package.outputs.artifact_name }}
           path: build/release
 
-      - name: Attach to GitHub release
+      - name: Publish release
         env:
           GH_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          VERSION: ${{ needs.package.outputs.version }}
+          RELEASE_ACTION: ${{ inputs.release_action }}
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
         run: |
-          TARBALL="build/release/nanokvm_${VERSION}.tar.gz"
+          ./scripts/verify-release-assets.sh build/release "$TAG"
-          TARBALL_NAME=$(basename "$TARBALL")
+
+          case "$RELEASE_ACTION" in
+            publish-prerelease) IS_PRERELEASE=true ;;
+            publish-stable) IS_PRERELEASE=false ;;
+            *)
+              echo "::error::invalid publish action '$RELEASE_ACTION'"
+              exit 1
+              ;;
+          esac
+
+          ENDPOINT="repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}"
+          set +e
+          HEADERS=$(gh api --include --silent "$ENDPOINT" 2>&1)
+          API_STATUS=$?
+          set -e
+          HTTP_STATUS=$(printf '%s\n' "$HEADERS" | awk '
+            $1 ~ /^HTTP\// { status = $2 }
+            END { print status }
+          ')
+          if [ "$API_STATUS" -eq 0 ] && [ "$HTTP_STATUS" = 200 ]; then
+            echo "::error::release or draft '$TAG' already exists"
+            echo "Publishing is one-shot. Inspect it at https://github.com/${GITHUB_REPOSITORY}/releases."
+            exit 1
+          fi
+          if [ "$API_STATUS" -eq 0 ] || [ "$HTTP_STATUS" != 404 ]; then
+            echo "::error::failed to query release '$TAG' (HTTP status: ${HTTP_STATUS:-unknown})"
+            printf '%s\n' "$HEADERS" >&2
+            exit 1
+          fi
+
+          TARBALL="build/release/nanokvm_${TAG}.tar.gz"
           SHA256=$(sha256sum "$TARBALL" | cut -d' ' -f1)
-          EXPECTED_SHA256_LINE="${SHA256}  ${TARBALL_NAME}"
+          SHA512=$(jq -er '.sha512' build/release/latest.json)
-          ACTUAL_SHA256_LINE=$(cat build/release/sha256.txt)
+          # Backticks below are intentional Markdown, not command substitution.
-          if [ "$ACTUAL_SHA256_LINE" != "$EXPECTED_SHA256_LINE" ]; then
+          # shellcheck disable=SC2016
-            echo "::error::sha256.txt does not match $TARBALL"
-            exit 1
-          fi
-          SHA512=$(jq -er '.sha512 | select(type == "string" and length > 0)' \
-            build/release/latest.json)
-          ACTUAL_SHA512=$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)
-          if [ "$SHA512" != "$ACTUAL_SHA512" ]; then
-            echo "::error::latest.json sha512 does not match $TARBALL"
-            exit 1
-          fi
-
-          CHECKSUM_BLOCK=$(printf '%s\n' \
-            "<!-- nanokvm-checksums:start -->" \
-            "### Checksums" \
-            "" \
-            "\`SHA-256\` (hex):" \
-            "" \
-            "    ${SHA256}" \
-            "" \
-            "\`SHA-512\` (base64, as expected by the on-device updater):" \
-            "" \
-            "    ${SHA512}" \
-            "<!-- nanokvm-checksums:end -->")
-
           NOTES=$(printf '%s\n' \
-            "Application package for NanoKVM ${VERSION}." \
+            "Application package for NanoKVM ${TAG}." \
-            "" \
+            '' \
-            "${CHECKSUM_BLOCK}" \
+            '### Checksums' \
-            "" \
+            '' \
-            "To offer this build over OTA, upload the tarball and \`latest.json\` to \`cdn.sipeed.com/nanokvm/\`.")
+            '`SHA-256` (hex):' \
+            '' \
+            "    ${SHA256}" \
+            '' \
+            '`SHA-512` (base64, as expected by the on-device updater):' \
+            '' \
+            "    ${SHA512}" \
+            '' \
+            'To offer this build over OTA, publish it through the separate CDN workflow.')
 
-          if gh release view "$VERSION" >/dev/null 2>&1; then
+          STATE_ARGS=(--prerelease="$IS_PRERELEASE")
-            echo "Release $VERSION exists; updating notes and assets"
+          if [ "$IS_PRERELEASE" = true ]; then
-            CURRENT_NOTES=$(gh release view "$VERSION" --json body --jq .body)
+            STATE_ARGS+=(--latest=false)
-            PRESERVED_NOTES=$(printf '%s\n' "$CURRENT_NOTES" | awk '
-              $0 == "<!-- nanokvm-checksums:start -->" { skip = 1; next }
-              $0 == "<!-- nanokvm-checksums:end -->" { skip = 0; next }
-              !skip { print }
-            ')
-            if [ -n "$PRESERVED_NOTES" ]; then
-              UPDATED_NOTES=$(printf '%s\n\n%s\n' "$PRESERVED_NOTES" "$CHECKSUM_BLOCK")
-            else
-              UPDATED_NOTES="$CHECKSUM_BLOCK"
-            fi
-            gh release upload "$VERSION" \
-              "$TARBALL" build/release/latest.json build/release/sha256.txt --clobber
-            # Publish the new checksums only after every asset upload succeeds.
-            gh release edit "$VERSION" --notes "$UPDATED_NOTES"
-          else
-            gh release create "$VERSION" \
-              --title "$VERSION" \
-              --notes "$NOTES" \
-              "$TARBALL" build/release/latest.json build/release/sha256.txt
           fi
+
+          ./scripts/verify-release-tag.sh "$TAG" "$SOURCE_SHA" >/dev/null
+          gh release create "$TAG" \
+            --verify-tag \
+            --title "$TAG" \
+            --notes "$NOTES" \
+            "${STATE_ARGS[@]}" \
+            "$TARBALL" build/release/latest.json build/release/sha256.txt
+
+      - name: Summary
+        env:
+          RELEASE_ACTION: ${{ inputs.release_action }}
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          {
+            echo '### NanoKVM GitHub Release published'
+            echo
+            echo "- Tag: \`$TAG\`"
+            echo "- Commit: \`$SOURCE_SHA\`"
+            echo "- Action: \`$RELEASE_ACTION\`"
+            echo
+            echo 'No CDN object was uploaded.'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  promote:
+    name: Promote verified prerelease
+    needs: validate
+    if: inputs.release_action == 'promote-stable'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout release tooling
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Verify and promote release
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          RELEASE_JSON=$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}")
+          if [ "$(jq -r '.draft' <<< "$RELEASE_JSON")" != false ]; then
+            echo "::error::release '$TAG' is a draft"
+            exit 1
+          fi
+          if [ "$(jq -r '.prerelease' <<< "$RELEASE_JSON")" != true ]; then
+            echo "::error::release '$TAG' is not a prerelease"
+            exit 1
+          fi
+
+          CURRENT_ASSETS=$(jq -r '.assets[].name' <<< "$RELEASE_JSON" | LC_ALL=C sort)
+          EXPECTED_ASSETS=$(printf '%s\n' \
+            latest.json "nanokvm_${TAG}.tar.gz" sha256.txt | LC_ALL=C sort)
+          if [ "$CURRENT_ASSETS" != "$EXPECTED_ASSETS" ]; then
+            echo "::error::release '$TAG' does not have the exact expected asset set"
+            exit 1
+          fi
+
+          mkdir -p build/release
+          gh release download "$TAG" --dir build/release \
+            --pattern "nanokvm_${TAG}.tar.gz" \
+            --pattern latest.json \
+            --pattern sha256.txt
+          ./scripts/verify-release-assets.sh build/release "$TAG"
+
+          ./scripts/verify-release-tag.sh "$TAG" "$SOURCE_SHA" >/dev/null
+          gh release edit "$TAG" --prerelease=false --latest
+          ./scripts/verify-release-tag.sh "$TAG" "$SOURCE_SHA" >/dev/null
+
+          if [ "$(gh api "repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}" --jq '.prerelease')" != false ]; then
+            echo "::error::release '$TAG' was not promoted"
+            exit 1
+          fi
+          if [ "$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq '.tag_name')" != "$TAG" ]; then
+            echo "::error::release '$TAG' was not marked latest"
+            exit 1
+          fi
+
+      - name: Summary
+        env:
+          SOURCE_SHA: ${{ needs.validate.outputs.source_sha }}
+          TAG: ${{ inputs.tag }}
+        run: |
+          {
+            echo '### NanoKVM prerelease promoted'
+            echo
+            echo "- Tag: \`$TAG\`"
+            echo "- Commit: \`$SOURCE_SHA\`"
+            echo '- Assets: unchanged and checksum-verified'
+            echo
+            echo 'No package was rebuilt and no CDN object was uploaded.'
+          } >> "$GITHUB_STEP_SUMMARY"

scripts/README.md

@@ -8,6 +8,8 @@ over the air: `nanokvm_<version>.tar.gz` plus its `latest.json` manifest.
 | `build-in-container.sh` | Builds every riscv64 artifact (`kvm_system`, `libkvm.so`, `NanoKVM-Server`). Runs inside the `nanokvm-builder` image only. |
 | `package.sh` | Stages the package tree, creates the tarball, and writes `latest.json`. |
 | `compare-release.sh` | Diffs a freshly built package against the currently published one. Informational. |
+| `verify-release-assets.sh` | Checks the three GitHub Release assets before publishing or promotion. |
+| `verify-release-tag.sh` | Requires an annotated numeric tag whose commit is on `main`. |
 
 ## What the updater expects
 
@@ -46,9 +48,13 @@ make web                   # web/dist
 make package VERSION=2.4.4 # build/release/{nanokvm_2.4.4.tar.gz,latest.json}
 ```
 
-In CI this runs as the **NanoKVM Package** workflow. Pull requests get a
+In CI this runs as the **NanoKVM Package** workflow. Pull requests and manual
-short-lived Actions artifact for device testing; pushing a `MAJOR.MINOR.PATCH`
+runs only create Actions artifacts. For a public release, run **NanoKVM Create
-tag creates or updates a GitHub release with three assets:
+Tag**, then run **NanoKVM Release** and choose prerelease, stable, or promotion.
+Publishing attaches three assets:
+
+Publishing is one-shot: an existing Release or draft is an error, and only a
+published prerelease can be promoted.
 
 - `nanokvm_<version>.tar.gz`
 - `latest.json`

scripts/verify-release-assets.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# Verify the three assets that make up a NanoKVM GitHub release.
+
+set -euo pipefail
+
+ASSET_DIR="${1:-}"
+VERSION="${2:-}"
+
+if [ -z "$ASSET_DIR" ] || [ -z "$VERSION" ]; then
+    echo "Usage: $0 <asset-directory> <version>" >&2
+    exit 1
+fi
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    echo "[ERROR] invalid version '$VERSION', expected MAJOR.MINOR.PATCH" >&2
+    exit 1
+fi
+
+TARBALL_NAME="nanokvm_${VERSION}.tar.gz"
+TARBALL="$ASSET_DIR/$TARBALL_NAME"
+MANIFEST="$ASSET_DIR/latest.json"
+CHECKSUM="$ASSET_DIR/sha256.txt"
+
+for path in "$TARBALL" "$MANIFEST" "$CHECKSUM"; do
+    if [ ! -f "$path" ]; then
+        echo "[ERROR] missing release asset: $path" >&2
+        exit 1
+    fi
+done
+
+PACKAGE_ROOT="nanokvm_${VERSION}"
+ENTRY_LIST=$(mktemp)
+VERBOSE_LIST=$(mktemp)
+trap 'rm -f "$ENTRY_LIST" "$VERBOSE_LIST"' EXIT
+
+if ! tar -tzf "$TARBALL" > "$ENTRY_LIST"; then
+    echo "[ERROR] could not list release tarball" >&2
+    exit 1
+fi
+if ! tar -tvzf "$TARBALL" > "$VERBOSE_LIST"; then
+    echo "[ERROR] could not inspect release tarball entry types" >&2
+    exit 1
+fi
+
+ENTRY_COUNT=0
+while IFS= read -r entry; do
+    ENTRY_COUNT=$((ENTRY_COUNT + 1))
+    case "$entry" in
+        "$PACKAGE_ROOT"|"$PACKAGE_ROOT"/*) ;;
+        *)
+            echo "[ERROR] archive entry is outside $PACKAGE_ROOT/: $entry" >&2
+            exit 1
+            ;;
+    esac
+    case "/$entry/" in
+        */../*|*/./*)
+            echo "[ERROR] archive entry contains an unsafe path component: $entry" >&2
+            exit 1
+            ;;
+    esac
+done < "$ENTRY_LIST"
+if [ "$ENTRY_COUNT" -eq 0 ]; then
+    echo "[ERROR] release tarball is empty" >&2
+    exit 1
+fi
+
+while IFS= read -r verbose_entry; do
+    entry_type=${verbose_entry:0:1}
+    case "$entry_type" in
+        -|d) ;;
+        *)
+            echo "[ERROR] archive contains a link or special entry: $verbose_entry" >&2
+            exit 1
+            ;;
+    esac
+done < "$VERBOSE_LIST"
+
+ARCHIVE_VERSION=$(tar -xOzf "$TARBALL" "$PACKAGE_ROOT/version" 2>/dev/null) || {
+    echo "[ERROR] release tarball does not contain $PACKAGE_ROOT/version" >&2
+    exit 1
+}
+if [ "$ARCHIVE_VERSION" != "$VERSION" ]; then
+    echo "[ERROR] archive version '$ARCHIVE_VERSION' does not match '$VERSION'" >&2
+    exit 1
+fi
+
+SHA256=$(sha256sum "$TARBALL" | cut -d' ' -f1)
+if ! printf '%s  %s\n' "$SHA256" "$TARBALL_NAME" | cmp -s - "$CHECKSUM"; then
+    echo "[ERROR] sha256.txt does not match $TARBALL_NAME" >&2
+    exit 1
+fi
+
+MANIFEST_VERSION=$(jq -er '.version | select(type == "string" and length > 0)' "$MANIFEST")
+MANIFEST_NAME=$(jq -er '.name | select(type == "string" and length > 0)' "$MANIFEST")
+MANIFEST_SIZE=$(jq -er '.size | select(type == "number" and . >= 0 and floor == .)' "$MANIFEST")
+MANIFEST_SHA512=$(jq -er '.sha512 | select(type == "string" and length > 0)' "$MANIFEST")
+
+if [ "$MANIFEST_VERSION" != "$VERSION" ]; then
+    echo "[ERROR] latest.json version '$MANIFEST_VERSION' does not match '$VERSION'" >&2
+    exit 1
+fi
+if [ "$MANIFEST_NAME" != "$TARBALL_NAME" ]; then
+    echo "[ERROR] latest.json name '$MANIFEST_NAME' does not match '$TARBALL_NAME'" >&2
+    exit 1
+fi
+
+ACTUAL_SIZE=$(wc -c < "$TARBALL" | tr -d ' ')
+if [ "$MANIFEST_SIZE" != "$ACTUAL_SIZE" ]; then
+    echo "[ERROR] latest.json size '$MANIFEST_SIZE' does not match '$ACTUAL_SIZE'" >&2
+    exit 1
+fi
+
+ACTUAL_SHA512=$(openssl dgst -sha512 -binary "$TARBALL" | openssl base64 -A)
+if [ "$MANIFEST_SHA512" != "$ACTUAL_SHA512" ]; then
+    echo "[ERROR] latest.json sha512 does not match $TARBALL_NAME" >&2
+    exit 1
+fi
+
+echo "[OK] verified NanoKVM release assets for $VERSION"

scripts/verify-release-tag.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Resolve an annotated numeric tag from origin and verify its commit is on main.
+
+set -euo pipefail
+
+TAG="${1:-}"
+EXPECTED_SHA="${2:-}"
+
+if ! echo "$TAG" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    echo "[ERROR] invalid tag '$TAG', expected MAJOR.MINOR.PATCH" >&2
+    exit 1
+fi
+if [ -n "$EXPECTED_SHA" ] && ! echo "$EXPECTED_SHA" | grep -qE '^[0-9a-f]{40}$'; then
+    echo "[ERROR] expected commit must be a full lowercase commit SHA" >&2
+    exit 1
+fi
+
+TAG_REF="refs/tags/$TAG"
+PEELED_REF="${TAG_REF}^{}"
+REMOTE_REFS=$(git ls-remote --tags origin "$TAG_REF" "$PEELED_REF")
+TAG_OBJECT=$(printf '%s\n' "$REMOTE_REFS" | awk -v ref="$TAG_REF" '$2 == ref { print $1 }')
+SOURCE_SHA=$(printf '%s\n' "$REMOTE_REFS" | awk -v ref="$PEELED_REF" '$2 == ref { print $1 }')
+
+if ! echo "$TAG_OBJECT" | grep -qE '^[0-9a-f]{40}$'; then
+    echo "[ERROR] tag '$TAG' does not exist on origin" >&2
+    exit 1
+fi
+if ! echo "$SOURCE_SHA" | grep -qE '^[0-9a-f]{40}$'; then
+    echo "[ERROR] tag '$TAG' is not an annotated tag" >&2
+    exit 1
+fi
+if [ -n "$EXPECTED_SHA" ] && [ "$SOURCE_SHA" != "$EXPECTED_SHA" ]; then
+    echo "[ERROR] tag '$TAG' moved from '$EXPECTED_SHA' to '$SOURCE_SHA'" >&2
+    exit 1
+fi
+
+git fetch --no-tags origin main
+if ! git merge-base --is-ancestor "$SOURCE_SHA" FETCH_HEAD; then
+    echo "[ERROR] tag '$TAG' points to a commit outside origin/main" >&2
+    exit 1
+fi
+
+printf '%s\n' "$SOURCE_SHA"