diff --git a/.ai/contexts/build-release.md b/.ai/contexts/build-release.md index 698bab6e2..280fe4a98 100644 --- a/.ai/contexts/build-release.md +++ b/.ai/contexts/build-release.md @@ -31,6 +31,15 @@ A failed or cancelled macOS tag build blocks automatic publication; no partial-p `continue-on-error` path exists. Recovery and manifest consistency requirements are in [releasing.md](../../docs/releasing.md). +`scripts/publish-release.sh` requires non-empty `GITHUB_REPOSITORY` and +`GITHUB_REF_NAME` before any gh call. The release lookup names the repository +in its API path; draft creation and every upload attempt pass +`--repo "${GITHUB_REPOSITORY}"`, so a clone's gh default cannot redirect writes. +The script tests execute Bash with a fake gh boundary and cover repository +selection, missing configuration, draft guards and upload retries. Manual +recovery downloads the tag run's artifacts, keeps the x64 copy of the colliding +pacman filename, then uses this script; see the release guide for commands. + Windows stays pinned to `windows-2022`: the Server 2025 image behind `windows-latest` lacks the Visual Studio C++ toolchain needed by node-gyp for node-pty. Linux stays split by architecture because electron-builder's native diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 4a5f581e0..57d5cd9f2 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -141,4 +141,4 @@ jobs: echo "**Full changelog**: ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/compare/${PREV_TAG}...${TAG}" >> release-notes.md fi # Stays a draft: edit only replaces the body. - gh release edit "$TAG" --notes-file release-notes.md + gh release edit "$TAG" --repo "${GITHUB_REPOSITORY}" --notes-file release-notes.md diff --git a/docs/releasing.md b/docs/releasing.md index 5ce848c28..eda074228 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -3,6 +3,9 @@ A release is a version tag on `main`. The version bump lands through a pull request first, because `main` is protected. +Every `gh` command run by hand in this clone needs `--repo devsuitup/switchboard`: +gh's default here is the upstream repository, `doctly/switchboard`. + ## Steps 1. **Bump the version and date the changelog** on a branch, and open the PR. @@ -31,7 +34,7 @@ request first, because `main` is protected. branch protection on `main` (`required_status_checks.contexts`). Both must be updated together whenever the test matrix changes; workflow changes do not change repository settings. The documented ruleset requires - no approving review, so `gh pr merge --auto --squash` can be armed once the + no approving review, so `gh pr merge --repo devsuitup/switchboard --auto --squash` can be armed once the required checks run. CI-only PRs use the `no-changelog` label. 2. **Run the app before tagging.** The tag is what publishes, and nothing @@ -68,11 +71,44 @@ request first, because `main` is protected. To recover, re-run the failed macOS job in the tag's Actions run (or re-run failed jobs) and let the dependent publish job run once every build succeeds. Alternatively, create the release draft by hand using only artifacts from - that tag's successful builds and the tag's changelog section. If macOS + that tag's successful builds. In Bash, replace `` with the tag's Actions + run ID and `` with its version: + + ```bash + gh run download --repo devsuitup/switchboard --dir .work-files/release-artifacts-v + ``` + + The download directory must not exist yet. Merge its `dist-*` artifact + directories into one fresh directory containing only the assets to upload. + Both Linux jobs produce `switchboard-doctly-.pacman` with the same + filename: keep the copy from `dist-linux-x64` and discard the arm64 copy. + (CI merges the artifacts with `merge-multiple`, so which copy CI publishes + depends on download order: v0.0.104 shipped the aarch64 copy.) If macOS artifacts are absent, omit `latest-mac.yml`. Never copy a previous release's mac manifest: upload it only when its version, filenames, sizes and hashes - match the macOS files actually attached to this release. Check the draft's - assets before publishing it as described below. + match the macOS files actually attached to this release. + + Create or complete the draft from the merged directory (``): + + ```bash + GITHUB_REPOSITORY=devsuitup/switchboard GITHUB_REF_NAME=v DIST_DIR= bash scripts/publish-release.sh + ``` + + Both GitHub variables must be set and non-empty; the script refuses before + calling gh otherwise. It reads and writes the explicitly named repository. + From a checkout containing the tag's `CHANGELOG.md`, extract and attach its + notes, then inspect the draft's asset names and sizes: + + ```bash + node scripts/changelog-section.js v > .work-files/release-notes.md + PREV_TAG="$(git describe --tags --abbrev=0 v^)" + printf '\n**Full changelog**: https://github.com/devsuitup/switchboard/compare/%s...v\n' "$PREV_TAG" >> .work-files/release-notes.md + gh release edit v --repo devsuitup/switchboard --notes-file .work-files/release-notes.md + gh release view v --repo devsuitup/switchboard --json assets --jq '.assets[] | {name, size}' + ``` + + Check those assets against the merged directory and verify the update + manifests before publishing the draft as described below. After all builds succeed, the publish job: - creates a **draft** release named after the version; @@ -85,12 +121,12 @@ request first, because `main` is protected. changelog** link comparing the previous tag with this one. It fails rather than publish an empty body when the section is missing or empty. The fix is then in `CHANGELOG.md`, through a PR; `gh release edit - --notes-file` can fill in the draft by hand meanwhile. + --repo devsuitup/switchboard --notes-file` can fill in the draft by hand meanwhile. Re-running CI while the release is a draft is fine: it completes or replaces the draft's assets. CI refuses to publish if it cannot read the releases, and never writes to a published release. Once published, add or replace an - asset by hand with `gh release upload --clobber` (see below), or tag a new + asset by hand with `gh release upload --repo devsuitup/switchboard --clobber` (see below), or tag a new version. Delete the draft or move the tag only while the release is still a draft. The workflow token has `contents: read`; only the publish job has `contents: write`, and no checkout persists credentials. @@ -151,7 +187,7 @@ can still receive a withdrawn pre-release. - **Tag the merged commit, never the local bump commit.** A squash merge makes a new commit; a tag on the pre-merge commit is not an ancestor of `main`, so `git describe --tags` and the release-notes range skip it. If a build already - started from such a tag, cancel it (`gh run cancel`), delete the tag locally + started from such a tag, cancel it (`gh run cancel --repo devsuitup/switchboard`), delete the tag locally and on `origin`, and tag the merged commit. - **Unsigned macOS builds need `"mac": {"identity": null}` and `"notarize": false` in `package.json`.** electron-builder reads a `CSC_LINK` diff --git a/scripts/publish-release.sh b/scripts/publish-release.sh index a59cc61a7..94687d817 100644 --- a/scripts/publish-release.sh +++ b/scripts/publish-release.sh @@ -2,6 +2,14 @@ set -e # see docs/releasing.md +if [ -z "${GITHUB_REPOSITORY:-}" ]; then + echo "::error::GITHUB_REPOSITORY must be set and non-empty" + exit 1 +fi +if [ -z "${GITHUB_REF_NAME:-}" ]; then + echo "::error::GITHUB_REF_NAME must be set and non-empty" + exit 1 +fi if ! draft="$(gh api --paginate "repos/${GITHUB_REPOSITORY}/releases?per_page=100" --jq ".[] | select(.tag_name == \"${GITHUB_REF_NAME}\") | .draft")"; then echo "::error::could not read the releases of ${GITHUB_REPOSITORY}; refusing to publish blind" exit 1 @@ -11,7 +19,7 @@ case "$draft" in gh release create "${GITHUB_REF_NAME}" \ --draft \ --title "${GITHUB_REF_NAME#v}" \ - --notes "" + --notes "" --repo "${GITHUB_REPOSITORY}" ;; true) echo "draft ${GITHUB_REF_NAME} already exists; proceeding to asset upload" ;; *$'\n'*) echo "::error::more than one release carries ${GITHUB_REF_NAME}; refusing to pick one"; exit 1 ;; @@ -22,7 +30,7 @@ for f in "${DIST_DIR:-dist}"/*; do [ -f "$f" ] || continue ok=0 for i in 1 2 3 4 5; do - if gh release upload "${GITHUB_REF_NAME}" "$f" --clobber; then ok=1; break; fi + if gh release upload "${GITHUB_REF_NAME}" "$f" --clobber --repo "${GITHUB_REPOSITORY}"; then ok=1; break; fi echo "::warning::upload $(basename "$f") attempt $i failed; retrying in ${RETRY_DELAY:-10}s" sleep "${RETRY_DELAY:-10}" done diff --git a/test/changelog-section.test.js b/test/changelog-section.test.js index 3e2709716..354679e10 100644 --- a/test/changelog-section.test.js +++ b/test/changelog-section.test.js @@ -45,5 +45,5 @@ test('the build workflow writes the release body from the tag\'s changelog secti const workflow = fs.readFileSync(path.join(ROOT, '.github', 'workflows', 'build.yml'), 'utf8'); const step = workflow.slice(workflow.indexOf('- name: Fill in release notes')); assert.match(step, /node scripts\/changelog-section\.js "\$TAG" > release-notes\.md/); - assert.match(step, /gh release edit "\$TAG" --notes-file release-notes\.md/); + assert.match(step, /gh release edit "\$TAG" --repo "\$\{GITHUB_REPOSITORY\}" --notes-file release-notes\.md/); }); diff --git a/test/publish-release.test.js b/test/publish-release.test.js index b0c29e543..9d0aed29d 100644 --- a/test/publish-release.test.js +++ b/test/publish-release.test.js @@ -45,7 +45,7 @@ echo 'unexpected gh invocation' >&2 exit 2 `; -function runRelease(t, mode, failOnce = false, draftValue = 'false') { +function runRelease(t, mode, failOnce = false, draftValue = 'false', envOverrides = {}) { const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'publish-release-')); t.after(() => fs.rmSync(temp, { recursive: true, force: true })); const bin = path.join(temp, 'bin'); @@ -75,6 +75,10 @@ function runRelease(t, mode, failOnce = false, draftValue = 'false') { GH_STUB_FAIL_ONCE: failOnce ? '1' : '0', GH_STUB_RETRY_FILE: shellPath(path.join(temp, 'retried')), }); + for (const [key, value] of Object.entries(envOverrides)) { + if (value === undefined) delete env[key]; + else env[key] = value; + } const result = spawnSync(bash, [shellPath(script)], { cwd: temp, env, encoding: 'utf8', timeout: 10000, }); @@ -94,7 +98,7 @@ function requireBash(t) { function assertUploads(result, names) { assert.deepEqual(result.calls.filter((args) => args[1] === 'upload'), names.map((name) => [ - 'release', 'upload', TAG, `${result.dist}/${name}`, '--clobber', + 'release', 'upload', TAG, `${result.dist}/${name}`, '--clobber', '--repo', REPOSITORY, ])); } @@ -109,7 +113,7 @@ test('given a missing release, publishing creates a draft and uploads both asset 'api', '--paginate', `repos/${REPOSITORY}/releases?per_page=100`, '--jq', `.[] | select(.tag_name == "${TAG}") | .draft`, ]); - assert.deepEqual(result.calls[1], ['release', 'create', TAG, '--draft', '--title', '0.1.0', '--notes', '']); + assert.deepEqual(result.calls[1], ['release', 'create', TAG, '--draft', '--title', '0.1.0', '--notes', '', '--repo', REPOSITORY]); assertUploads(result, ['one.zip', 'two.exe']); }); @@ -158,3 +162,26 @@ test('given a draft and one failed upload, publishing retries and exits 0', (t) assert.match(result.stdout, /attempt 1 failed; retrying in 0s/); assertUploads(result, ['one.zip', 'one.zip', 'two.exe']); }); + +for (const variable of ['GITHUB_REPOSITORY', 'GITHUB_REF_NAME']) { + for (const value of [undefined, '']) { + test(`given ${variable} is ${value === undefined ? 'unset' : 'empty'}, publishing refuses before calling gh`, (t) => { + if (!requireBash(t)) return; + const result = runRelease(t, 'missing', false, 'false', { [variable]: value }); + assert.equal(result.status, 1, `${variable} must be required`); + assert.match(result.stdout + result.stderr, new RegExp(`::error::.*${variable}`)); + assert.deepEqual(result.calls, [], 'invalid configuration must not call gh'); + }); + } +} + +test('given another repository, publishing reads and writes that repository', (t) => { + if (!requireBash(t)) return; + const repository = 'another-owner/release-target'; + const result = runRelease(t, 'missing', false, 'false', { GITHUB_REPOSITORY: repository }); + assert.equal(result.status, 0, result.stderr); + assert.equal(result.calls[0][2], `repos/${repository}/releases?per_page=100`); + for (const call of result.calls.slice(1)) { + assert.deepEqual(call.slice(-2), ['--repo', repository]); + } +});