From 42bf14d9d28dade3534fcf003571e09ae41d6217 Mon Sep 17 00:00:00 2001 From: Yidi Mao Date: Fri, 16 Oct 2026 06:38:01 +0300 Subject: [PATCH] docs: record release pipeline learnings (allow-list, dry run, tag ruleset, poll) - Require allowing microsoft/microsoft-store-apppublisher in Actions settings - Document the absolute PACKAGE_DIR, cert trust before verify, the dry run trigger and how to re-point a tag under the protect-release-tags ruleset - Note that submission poll returns while still in certification - Add release-workflow troubleshooting entries; release skill points to the dry run --- .claude/skills/release/SKILL.md | 2 ++ docs/PUBLISHING.md | 9 ++++++++- docs/TROUBLESHOOTING.md | 7 +++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index c50cb04..9bd0a5f 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -25,6 +25,8 @@ The fourth segment stays `.0` (Store rule). Then grep tracked files (not `bin/`, Delete `bin`, `obj` and `AppPackages` if identity, name or publish profiles changed, then run the restore + `--no-restore` unsigned bundle build from `docs/PUBLISHING.md` (the `bundle-build` job in `ci.yml` runs the same command on every PR; run it locally to debug a failure). A bundle at repo-root `AppPackages/UnityExtension__Test/UnityExtension__x64_arm64.msixbundle` means it worked. Optionally sideload-test it via the `deploy` skill. +If `release-msix.yml` or its pinned actions changed since the last release, run the dry run first (`gh workflow run release-msix.yml --ref `; builds, signs, verifies and uploads, publishes nothing). Tags are hard to redo because of the `protect-release-tags` ruleset. + The version must be higher than the one last published to the Store (`winget show` does not report it; ask the user or check Partner Center), and no draft may be open in the Partner Center web UI. ## 3. Commit and tag diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 6cf43af..7f93b47 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -107,6 +107,12 @@ For local-dev tester trust, keep one reusable signing cert and store the private - `MSIX_PFX_PASSWORD` — the PFX password - `UnityExtension\BundleArtifacts\Maoyeedy-MSIX-LocalDev.cer` — public certificate for testers +The workflow's `PACKAGE_DIR` must stay absolute (`${{ github.workspace }}\...`): MSBuild resolves a relative `AppxPackageDir` against the project folder, so the bundle would otherwise land where the "Find MSIX bundle" step does not look. The verify step imports the `.cer` into `LocalMachine\TrustedPeople` first, because a clean runner does not trust the self-signed cert. + +**Dry run:** `gh workflow run release-msix.yml --ref ` (or Actions > Release MSIX > Run workflow) builds, signs, verifies and uploads the artifact without creating a release or touching the Store. Use it to test workflow changes (including action bumps) before tagging; the GitHub release and `store-publish` steps run only for tags. + +**Re-pointing a tag:** the `protect-release-tags` ruleset blocks deleting or updating `v*` tags, and a run that fails at startup cannot be retried. To redo a tag, temporarily set the ruleset's enforcement to Disabled (repo Settings > Rules > Rulesets, not the read-only Rules page), then `git tag -f vX.Y.Z && git push origin :refs/tags/vX.Y.Z && git push origin vX.Y.Z`, then set it back to Active. Prefer the dry run so this is rarely needed. + ### Microsoft Store updates (automated) The first Store submission was done in Partner Center; updates can use the `store-publish` job in `release-msix.yml`. It is off until you opt in. @@ -120,8 +126,9 @@ One-time setup: 5. Repo variable `STORE_PUBLISH=true` (set it to `false` to pause the job). 6. Settings > Environments > `microsoft-store`: add yourself as required reviewer so each submission waits for approval. 7. Locally: `msstore reconfigure --tenantId ... --sellerId ... --clientId ... --clientSecret ...`. The interactive form can fail with "Error while retrieving Organization"; the flags work. +8. Settings > Actions > General: the repo restricts allowed actions, so add `microsoft/microsoft-store-apppublisher@*` to the allow list. Without it the whole release workflow fails at startup (`startup_failure`, zero jobs, no rerun possible), including the build job. -On a `v*` tag the job downloads the built bundle and runs `msstore publish -id 9NVSJZ72LTZ3`, then `msstore submission poll`. The Store re-signs the package, so the self-signed PFX does not matter. Only free apps are supported by the CLI; the version must be higher than the last published one, so bump the version before tagging. A `.msixbundle` path works with `publish` (verified with `--noCommit`). +On a `v*` tag the job downloads the built bundle and runs `msstore publish -id 9NVSJZ72LTZ3`, then `msstore submission poll`. The poll step returns once the submission is committed and in certification; it does not wait for it to go live, so a green run means "accepted", not "published". Check `msstore submission status 9NVSJZ72LTZ3` or Partner Center for the result. The Store re-signs the package, so the self-signed PFX does not matter. Only free apps are supported by the CLI; the version must be higher than the last published one, so bump the version before tagging. A `.msixbundle` path works with `publish` (verified with `--noCommit`). Before tagging a release: diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index f39b673..6e6c163 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -48,6 +48,13 @@ If packaging fails with `IL2104` / `NETSDK1144`, check trimming enabled for pack - `NETSDK1094` "Unable to optimize assemblies for performance": the two publish profiles disagree on `PublishReadyToRun`, so restore skipped one architecture's runtime pack. Make `win-x64.pubxml` and `win-arm64.pubxml` match, delete `bin`/`obj`/`AppPackages`, then restore and build again. The ILLink crash (exit code `-1073741819`) showed up in the same state. - Signing verification says "root certificate not trusted" or install fails: trust the cert in `Cert:\LocalMachine\TrustedPeople` from an elevated shell; `CurrentUser` is not enough. +## Release workflow errors + +- `startup_failure` with zero jobs: an action is not allowed by the repo's Actions policy (Settings > Actions > General). Allow `microsoft/microsoft-store-apppublisher@*`. Such runs cannot be retried; push the tag again (see "Re-pointing a tag" in [`PUBLISHING.md`](PUBLISHING.md#github-releases-flow)). +- "No .msixbundle found" after a successful build: `PACKAGE_DIR` must be absolute; a relative `AppxPackageDir` is resolved against the project folder. +- `SignTool Error: ... root certificate which is not trusted` in "Verify MSIX bundle": the self-signed `.cer` must be imported into `LocalMachine\TrustedPeople` before `signtool verify`. +- A green run does not mean the update is live; `submission poll` returns while the submission is still in certification. + ## Store publishing errors - "Ingestion API can only update, delete, and commit submissions that are created through the API": a draft made in the Partner Center web UI blocks `msstore`. Delete or submit it in the portal first (CI would hang on the browser prompt).