Skip to content

Your lightweight open-source personal agent.

ci(release): verify exact candidate wheels on all five native targets

Xubin Ren897c8b013f4a
diff --git a/.github/workflows/native-acceptance.yml b/.github/workflows/native-acceptance.yml
index 4ae00231c..4c741425e 100644
--- a/.github/workflows/native-acceptance.yml
+++ b/.github/workflows/native-acceptance.yml
@@ -13,12 +13,13 @@ on:
manifest_sha256:
type: string
default: ''
- linux_artifact_id:
+ candidate_artifact_id:
type: string
default: ''
- windows_artifact_id:
+ platforms:
+ description: Native runner and wheel pairs; ordinary PRs keep the two-platform budget
type: string
- default: ''
+ default: '[{"os":"ubuntu-latest","target":"linux-x64","wheel_tag":"manylinux_2_17_x86_64"},{"os":"windows-latest","target":"win32-x64","wheel_tag":"win_amd64"}]'
permissions:
contents: read
@@ -31,13 +32,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- include:
- - os: ubuntu-latest
- target: linux-x64
- wheel_tag: manylinux_2_17_x86_64
- - os: windows-latest
- target: win32-x64
- wheel_tag: win_amd64
+ include: ${{ fromJSON(inputs.platforms) }}
defaults:
run:
shell: bash
@@ -81,7 +76,7 @@ jobs:
uses: actions/download-artifact@v4
with:
# Producer IDs survive a failed-jobs-only retry without rebuilding bytes.
- artifact-ids: ${{ matrix.target == 'linux-x64' && inputs.linux_artifact_id || inputs.windows_artifact_id }}
+ artifact-ids: ${{ inputs.candidate_artifact_id }}
merge-multiple: true
path: ${{ runner.temp }}/native-wheel
diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml
index b6e6f6e4b..fb7e37e9f 100644
--- a/.github/workflows/release-candidate.yml
+++ b/.github/workflows/release-candidate.yml
@@ -36,8 +36,7 @@ jobs:
outputs:
candidate_commit: ${{ steps.identity.outputs.candidate_commit }}
manifest_sha256: ${{ steps.identity.outputs.manifest_sha256 }}
- linux_artifact_id: ${{ steps.linux_input.outputs.artifact-id }}
- windows_artifact_id: ${{ steps.windows_input.outputs.artifact-id }}
+ candidate_artifact_id: ${{ steps.native_input.outputs.artifact-id }}
prepared_artifact_id: ${{ steps.prepared.outputs.artifact-id }}
env:
SOURCE_COMMIT: ${{ github.sha }}
@@ -164,25 +163,13 @@ jobs:
PY
# Temporary same-run inputs, not approved release handoffs. Do not rebuild on consumers.
- - name: Transfer exact Linux acceptance input
- id: linux_input
+ - name: Transfer exact native acceptance inputs
+ id: native_input
uses: actions/upload-artifact@v4
with:
- name: candidate-native-linux-x64-${{ github.run_number }}-${{ github.run_attempt }}
+ name: candidate-native-wheels-${{ github.run_number }}-${{ github.run_attempt }}
path: |
- ${{ runner.temp }}/release-artifacts/*-manylinux_2_17_x86_64.whl
- ${{ runner.temp }}/release-artifacts/release-manifest.json
- if-no-files-found: error
- retention-days: 1
- compression-level: 0
-
- - name: Transfer exact Windows acceptance input
- id: windows_input
- uses: actions/upload-artifact@v4
- with:
- name: candidate-native-win32-x64-${{ github.run_number }}-${{ github.run_attempt }}
- path: |
- ${{ runner.temp }}/release-artifacts/*-win_amd64.whl
+ ${{ runner.temp }}/release-artifacts/*.whl
${{ runner.temp }}/release-artifacts/release-manifest.json
if-no-files-found: error
retention-days: 1
@@ -236,8 +223,13 @@ jobs:
candidate: true
candidate_commit: ${{ needs.candidate.outputs.candidate_commit }}
manifest_sha256: ${{ needs.candidate.outputs.manifest_sha256 }}
- linux_artifact_id: ${{ needs.candidate.outputs.linux_artifact_id }}
- windows_artifact_id: ${{ needs.candidate.outputs.windows_artifact_id }}
+ candidate_artifact_id: ${{ needs.candidate.outputs.candidate_artifact_id }}
+ platforms: >-
+ [{"os":"ubuntu-latest","target":"linux-x64","wheel_tag":"manylinux_2_17_x86_64"},
+ {"os":"ubuntu-24.04-arm","target":"linux-arm64","wheel_tag":"manylinux_2_17_aarch64"},
+ {"os":"windows-latest","target":"win32-x64","wheel_tag":"win_amd64"},
+ {"os":"macos-15","target":"darwin-arm64","wheel_tag":"macosx_13_0_arm64"},
+ {"os":"macos-15-intel","target":"darwin-x64","wheel_tag":"macosx_13_0_x86_64"}]
verified:
name: Candidate required
@@ -246,7 +238,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- - name: Require build and both native acceptance jobs
+ - name: Require build and every native acceptance job
env:
BUILD_RESULT: ${{ needs.candidate.result }}
NATIVE_RESULT: ${{ needs.native.result }}
@@ -275,5 +267,5 @@ jobs:
CANDIDATE_COMMIT: ${{ needs.candidate.outputs.candidate_commit }}
MANIFEST_SHA256: ${{ needs.candidate.outputs.manifest_sha256 }}
run: |
- printf 'Candidate: `%s`\n\nManifest SHA-256: `%s`\n\nLinux and Windows native acceptance passed. Publication requires separate approval.\n' \
+ printf 'Candidate: `%s`\n\nManifest SHA-256: `%s`\n\nAll five native targets passed installation and update/recovery acceptance. Publication requires separate approval.\n' \
"$CANDIDATE_COMMIT" "$MANIFEST_SHA256" >> "$GITHUB_STEP_SUMMARY"
diff --git a/docs/releasing.md b/docs/releasing.md
index dc723072d..7f7d333b1 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -24,8 +24,8 @@ Packaging is maintainer-triggered, not scheduled or push-triggered. Record the r
### Maintainer-triggered Preview procedure
1. Select an exact reviewed `main` commit with passing required CI; skip it if its source SHA matches the last accepted candidate. Record the next unreleased stable base and an unused increasing Preview sequence.
-2. Run **Verify Release Candidate** for that ref and base. It prepares a version-only candidate, builds the WebUI and five native TUI bundles once, and runs Linux x64 and Windows x64 clean-install and packaged update/recovery acceptance against the exact manifest-bound wheels without publication. Require the **Candidate required** check to pass; build-only reports are insufficient. Users receive built packages, not a checkout requiring Bun.
-3. Select `retain_installable` and preserve the accepted `installable-candidate` handoff before expiry. Temporary `candidate-native` inputs and `prepared-candidate` artifacts are not accepted handoffs. Complete the remaining native-platform and real historical-baseline acceptance against those exact bytes; the automated fault-injection fixtures do not establish compatibility with a previously published version. Keep candidate SHA, manifest hash, coverage, known issues and source-offer approval together; CI reports alone are neither installable artifacts nor publication consent.
+2. Run **Verify Release Candidate** for that ref and base. It prepares a version-only candidate, builds the WebUI and five native TUI bundles once, and runs macOS arm64/x64, Linux arm64/x64 and Windows x64 clean-install and packaged update/recovery acceptance against the exact manifest-bound wheels without publication. Ordinary PR CI keeps its Linux x64/Windows x64 matrix; the manually requested candidate pays for all five native runners. Require the **Candidate required** check to pass; build-only reports are insufficient. Users receive built packages, not a checkout requiring Bun.
+3. Select `retain_installable` and preserve the accepted `installable-candidate` handoff before expiry. Temporary `candidate-native` inputs and `prepared-candidate` artifacts are not accepted handoffs. Complete real historical-baseline and interactive acceptance against those exact bytes; the automated fault-injection fixtures do not establish compatibility with a previously published version or interactive desktop behavior. Keep candidate SHA, manifest hash, coverage, known issues and source-offer approval together; CI reports alone are neither installable artifacts nor publication consent.
4. With separate approval, publish immutable `v<version>` at the **candidate** commit and a GitHub prerelease, never the latest stable release. Upload the complete verified set, manifest and notes; make the pinned installer source publicly reachable.
5. Verify all public sizes/hashes and clean public install/update acceptance before advancing `preview` with a new catalogue generation. Validate against the latest catalogue, preserve `stable` and withdrawals, and serialize stable, Preview and withdrawal writes. A stale publisher must reread and revalidate.
6. After partial upload, leave the feed unchanged and resume only from the original verified files. Lost or changed bytes require a new version and repeated acceptance. Withdraw unsafe candidates with a reason and offer a newer fix; never rewind the feed or restore user data.
@@ -103,7 +103,7 @@ PyPI receives **five platform wheels and one sdist**, not the intermediate unive
Final releases also require `release-manifest.json` for `stable`. Run `scripts.release_candidate assemble` as shown below from the clean final-version checkout, using that final commit as `--source-commit` without Preview preparation. GitHub receives the same wheels/sdist, ten archive/checksum files and manifest; PyPI receives only wheels/sdist. Verify final source and public bytes before catalogue advancement. A TUI-only GitHub Release cannot deliver the final release to Preview subscribers.
-For the same-build Linux and Windows candidate acceptance, run **Verify Release Candidate** at the exact final-version ref with `channel=stable`, `next_stable` equal to that declared version and `retain_installable=true`. Stable preparation copies the exact commit without changing version declarations or creating a Preview commit; it rejects mismatched versions and existing stable tags. The default `channel=preview` retains the version-only Preview preparation. Both modes are read-only preparation, require **Candidate required** and retain accepted files for one day; neither publishes a tag, release, PyPI package or feed. Download and independently preserve the accepted handoff before expiry, then complete native macOS and historical-owner acceptance against that same manifest.
+For same-build candidate acceptance on all five native targets, run **Verify Release Candidate** at the exact final-version ref with `channel=stable`, `next_stable` equal to that declared version and `retain_installable=true`. Stable preparation copies the exact commit without changing version declarations or creating a Preview commit; it rejects mismatched versions and existing stable tags. The default `channel=preview` retains the version-only Preview preparation. Both modes are read-only preparation, require **Candidate required** and retain accepted files for one day; neither publishes a tag, release, PyPI package or feed. Download and independently preserve the accepted handoff before expiry, then complete remaining interactive and real historical-owner acceptance against that same manifest.
## Publish, with maintainer approval
@@ -160,7 +160,7 @@ These exact-version handoffs do not discover Preview, change subscriptions, stop
### Packaged upgrade and recovery acceptance
-Linux/Windows native CI runs `scripts/verify_packaged_update.py` against its wheel; manual candidate preparation uses the assembled Linux wheel. Run macOS acceptance against the candidate's macOS wheel:
+Linux/Windows native CI runs `scripts/verify_packaged_update.py` against its wheel; manual candidate preparation tests each of the five assembled platform wheels on a matching native runner. Run macOS acceptance against the candidate's macOS wheel:
```bash
<build-tools-python> -I scripts/verify_packaged_update.py \
@@ -212,7 +212,7 @@ Discovery grants no installation authority. Only the official managed venv and s
Default retention is small identity/manifest/probe reports and installation guide for **three days**, without installable binaries. `retain_installable` preserves those exact checked artifacts plus a self-contained shallow Git repository for **one day** (about 400 MB). Keep this storage exception off for routine preflight or schedules; assess storage and call it out explicitly in workflow-change PRs before merge. Preserve approved handoffs before expiry; rebuilding expired files cannot reuse their verification. The source contains only candidate/source-parent history, not configuration or untracked files. `handoff.json` is written only after copied artifacts verify; interruption is not an accepted handoff.
-After assembly, the workflow installs the Linux x64 wheel and binary dependencies into a separate venv without Bun/Node/Git on the install PATH. Isolated Python checks version/commit/import identity, all Vite-manifest assets including lazy chunks through the installed handler, and bundled TUI `--desktop-protocol` with downloads disabled and empty private HOME. With `--gateway`, it starts a private foreground CLI gateway with no provider/MCP configuration, disabled heartbeat and two loopback ports, then checks readiness, protected version identity, HTML and process/listener cleanup. Unix shutdown must be graceful; Windows termination is labelled, not graceful-shutdown evidence. No model task or external channel is exercised.
+After assembly, the workflow transfers all five manifest-bound wheels by immutable artifact ID; each matching native runner installs its wheel and binary dependencies into a separate venv without Bun/Node/Git on the install PATH. Isolated Python checks version/commit/import identity, all Vite-manifest assets including lazy chunks through the installed handler, and bundled TUI `--desktop-protocol` with downloads disabled and empty private HOME. With `--gateway`, it starts a private foreground CLI gateway with no provider/MCP configuration, disabled heartbeat and two loopback ports, then checks readiness, protected version identity, HTML and process/listener cleanup. Unix shutdown must be graceful; Windows termination is labelled, not graceful-shutdown evidence. No model task or external channel is exercised.
On another supported platform, check a disposable native installation without changing its package:
diff --git a/tests/scripts/test_ci_workflows.py b/tests/scripts/test_ci_workflows.py
index 1d54783d8..f47c79594 100644
--- a/tests/scripts/test_ci_workflows.py
+++ b/tests/scripts/test_ci_workflows.py
@@ -1,8 +1,8 @@
"""Producer/consumer artifact wiring must survive failed-jobs-only retries."""
+import json
from pathlib import Path
-import pytest
import yaml
WORKFLOWS = Path(__file__).resolve().parents[2] / ".github/workflows"
@@ -12,10 +12,10 @@ def workflow(name):
return yaml.load((WORKFLOWS / name).read_text(encoding="utf-8"), Loader=yaml.BaseLoader)
[email protected]("platform,step", [("linux", "linux_input"), ("windows", "windows_input")])
-def test_native_consumers_receive_immutable_producer_ids(platform, step):
+def test_native_consumers_receive_immutable_producer_ids():
jobs = workflow("release-candidate.yml")["jobs"]
- key = f"{platform}_artifact_id"
+ key = "candidate_artifact_id"
+ step = "native_input"
producer = jobs["candidate"]
assert producer["outputs"][key] == "${{ steps." + step + ".outputs.artifact-id }}"
upload = next(item for item in producer["steps"] if item.get("id") == step)
@@ -28,6 +28,22 @@ def test_native_consumers_receive_immutable_producer_ids(platform, step):
assert download["with"]["merge-multiple"] == "true"
+def test_candidate_executes_all_five_native_wheels_without_expanding_pr_matrix():
+ native = workflow("native-acceptance.yml")
+ assert native["jobs"]["native"]["strategy"]["matrix"]["include"] == "${{ fromJSON(inputs.platforms) }}"
+ defaults = json.loads(native["on"]["workflow_call"]["inputs"]["platforms"]["default"])
+ assert {item["target"] for item in defaults} == {"linux-x64", "win32-x64"}
+ candidate = workflow("release-candidate.yml")["jobs"]["native"]["with"]
+ assert candidate["candidate"] == "true"
+ assert {(item["os"], item["target"], item["wheel_tag"]) for item in json.loads(candidate["platforms"])} == {
+ ("ubuntu-latest", "linux-x64", "manylinux_2_17_x86_64"),
+ ("ubuntu-24.04-arm", "linux-arm64", "manylinux_2_17_aarch64"),
+ ("windows-latest", "win32-x64", "win_amd64"),
+ ("macos-15", "darwin-arm64", "macosx_13_0_arm64"),
+ ("macos-15-intel", "darwin-x64", "macosx_13_0_x86_64"),
+ }
+
+
def test_accepted_handoff_uses_the_producer_id_and_requires_native_success():
jobs = workflow("release-candidate.yml")["jobs"]
assert jobs["candidate"]["outputs"]["prepared_artifact_id"] == "${{ steps.prepared.outputs.artifact-id }}"