ci: allow tagged package recovery

Author: maikebing

.github/workflows/build.yml

@@ -9,6 +9,10 @@ on:
         description: 'DEB version; leave blank for an automatic CI or tag version'
         required: false
         type: string
+      release_tag:
+        description: 'Existing vX.Y.Z tag to rebuild and publish; leave blank for artifact only'
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -18,6 +22,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+        with:
+          ref: ${{ inputs.release_tag || github.ref }}
       - name: Build userspace and tools
         run: make userspace
       - name: Test readiness checker
@@ -31,6 +37,8 @@ jobs:
       KERNEL_RELEASE: 4.15.0-60-generic
     steps:
       - uses: actions/checkout@v5
+        with:
+          ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Build target-kernel module without a bind mount
         shell: bash
@@ -68,13 +76,17 @@ jobs:
     needs: kernel-4-15
     outputs:
       version: ${{ steps.version.outputs.version }}
+      source_revision: ${{ steps.version.outputs.source_revision }}
     env:
       KERNEL_RELEASE: 4.15.0-60-generic
       KERNEL_ARCHITECTURE: i386
       PCCT_IMAGE: ghcr.io/iotsharp/pcct-build-x86:latest
       REQUESTED_VERSION: ${{ inputs.version }}
+      RELEASE_TAG: ${{ inputs.release_tag }}
     steps:
       - uses: actions/checkout@v5
+        with:
+          ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Download target-kernel module
         uses: actions/download-artifact@v4
@@ -87,7 +99,21 @@ jobs:
         shell: bash
         run: |
           set -eu
-          if [ -n "$REQUESTED_VERSION" ]; then
+          if [ -n "$RELEASE_TAG" ]; then
+            case "$RELEASE_TAG" in
+              v[0-9]*) ;;
+              *)
+                printf 'Invalid release tag: %s\n' "$RELEASE_TAG" >&2
+                exit 2
+                ;;
+            esac
+            version="${RELEASE_TAG#v}"
+            if [ -n "$REQUESTED_VERSION" ] && [ "$REQUESTED_VERSION" != "$version" ]; then
+              printf 'Version %s does not match release tag %s\n' \
+                "$REQUESTED_VERSION" "$RELEASE_TAG" >&2
+              exit 2
+            fi
+          elif [ -n "$REQUESTED_VERSION" ]; then
             version="$REQUESTED_VERSION"
           elif [[ "$GITHUB_REF" == refs/tags/v* ]]; then
             version="${GITHUB_REF_NAME#v}"
@@ -102,6 +128,7 @@ jobs:
             *) ;;
           esac
           printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
+          printf 'source_revision=%s\n' "$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           printf 'Building USBDisplayStack version %s\n' "$version"
 
       - name: Build and package with PCCT
@@ -149,7 +176,9 @@ jobs:
 
   publish-tag:
     name: publish tagged Debian package
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    if: >-
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      (github.event_name == 'workflow_dispatch' && inputs.release_tag != '')
     runs-on: ubuntu-latest
     needs: debian-package
     permissions:
@@ -158,6 +187,8 @@ jobs:
     env:
       OCI_PACKAGE: ghcr.io/iotsharp/usbdisplaystack-deb
       PACKAGE_VERSION: ${{ needs.debian-package.outputs.version }}
+      RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
+      SOURCE_REVISION: ${{ needs.debian-package.outputs.source_revision }}
     steps:
       - name: Download Debian package
         uses: actions/download-artifact@v4
@@ -181,13 +212,13 @@ jobs:
             printf 'Expected three release assets, found %s\n' "${#assets[@]}" >&2
             exit 1
           fi
-          if ! gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
-            gh release create "$GITHUB_REF_NAME" \
+          if ! gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+            gh release create "$RELEASE_TAG" \
               --verify-tag \
-              --title "$GITHUB_REF_NAME" \
+              --title "$RELEASE_TAG" \
               --generate-notes
           fi
-          gh release upload "$GITHUB_REF_NAME" "${assets[@]}" --clobber
+          gh release upload "$RELEASE_TAG" "${assets[@]}" --clobber
 
       - name: Install ORAS
         uses: oras-project/setup-oras@v1
@@ -207,10 +238,10 @@ jobs:
           printf '%s' "$GHCR_TOKEN" | oras login ghcr.io \
             --username "$GITHUB_ACTOR" \
             --password-stdin
-          oras push "$OCI_PACKAGE:$GITHUB_REF_NAME" \
+          oras push "$OCI_PACKAGE:$RELEASE_TAG" \
             --artifact-type application/vnd.iotsharp.usbdisplaystack.debian.v1 \
             --annotation "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY" \
-            --annotation "org.opencontainers.image.revision=$GITHUB_SHA" \
+            --annotation "org.opencontainers.image.revision=$SOURCE_REVISION" \
             --annotation "org.opencontainers.image.version=$PACKAGE_VERSION" \
             --annotation "org.opencontainers.image.title=USBDisplayStack Debian package" \
             "$package:application/vnd.debian.binary-package" \

README.md

@@ -217,8 +217,9 @@ workflow artifact. A `vX.Y.Z` tag uses `X.Y.Z` and also publishes those files to
 the matching GitHub Release. The same tagged files are mirrored in GitHub
 Packages as the OCI artifact `ghcr.io/iotsharp/usbdisplaystack-deb:vX.Y.Z`;
 GitHub Packages does not provide a native Debian/APT package registry. The
-manual workflow dispatch can override the artifact version but does not publish
-a release or package.
+manual workflow dispatch can override the artifact version without publishing.
+Maintainers can instead set `release_tag` to an existing `vX.Y.Z` tag to rebuild
+that tag and recover its Release and Package assets.
 
 The package contains its Debian lifecycle hooks and all project installation
 scripts. It deliberately does not activate the module or select the physical

README.zh-CN.md

@@ -193,7 +193,8 @@ GitHub Actions 会在每次 push 和 pull request 时执行同一套 PCCT 打包
 标签时使用 `X.Y.Z` 作为包版本，并把这三个文件上传到同名 GitHub Release；同时
 以 OCI artifact `ghcr.io/iotsharp/usbdisplaystack-deb:vX.Y.Z` 镜像到 GitHub
 Packages。GitHub Packages 本身不提供原生 Debian/APT 软件源类型。手动运行
-workflow 可以填写 artifact 版本号，但不会发布 Release 或 Package。
+workflow 时只填写版本号不会发布；维护者也可以把 `release_tag` 设为已有的
+`vX.Y.Z` 标签，从该标签重建并恢复对应的 Release 和 Package 资产。
 
 DEB 已包含 Debian 生命周期脚本和项目的全部安装/卸载脚本。出于现场安全和
 replay 授权边界，安装后仍不会自动加载模块、选择实体后端或启动服务。离线安装、