learnharness/docs/gitea-release.md

Gitea releases for this fork

The release destination is https://server2.sorokin-oleg-edu.xyz/replicated/learnharness. Version 0.5.1 targets Linux x64 and Windows x64, with each platform built and verified on its native operating system. The upstream GitHub workflow and three-platform packaging configuration remain available as reference in .github/workflows/release.yml and electron-builder.yml.

Official fork packages use electron-builder.gitea.yml, which inherits the upstream packaging and replaces its update origin with:

https://server2.sorokin-oleg-edu.xyz/replicated/learnharness/releases/download/latest

Gitea's latest alias resolves the most recent published, non-prerelease release. Drafts do not become updates. The repository and published downloads must be public; no API credential is embedded in the application.

Preparing Linux packages

Use Node 26, matching upstream's release gates. Build from a clean checkout of the intended release commit. Keep .env*, local keys, and application data out of the build directory. Next can copy loaded environment files after tracing; build-server.mjs refuses a payload containing them. A clean worktree avoids loading these files in the first place.

npm ci
npm run typecheck
npm test
npm run lint
ELECTRON_RUN_AS_NODE=1 npx electron --import tsx --test tests/pdf-native-render.test.ts tests/pdf-ops.test.ts tests/svg-native-render.test.ts tests/browser-service.test.ts
npm run desktop:release:linux

The release script builds the standalone server, initializes providers offline, curates the payload, boots it under Electron's bundled Node, packages AppImage and Debian installers, checks the packaged Gitea updater configuration, creates SHA-256 checksums, and verifies update metadata against the actual installer bytes.

Run the packaged-runtime gates too:

node scripts/smoke-provider-runtime.mjs --standalone dist/linux-unpacked/resources/server/standalone
node scripts/smoke-provider-runtime.mjs --standalone dist/linux-unpacked/resources/server/standalone --runtime dist/linux-unpacked/learnharness
xvfb-run -a node scripts/smoke-demo-runtime.mjs --standalone dist/linux-unpacked/resources/server/standalone --runtime dist/linux-unpacked/learnharness --browser

The Linux portion of 0.5.1 has these attachments:

• LearnHarness-0.5.1-x86_64.AppImage
• LearnHarness-0.5.1-amd64.deb
• latest-linux.yml
• SHA256SUMS

Preparing Windows packages

Use a clean checkout of the same v0.5.1 tag on Windows x64 with Node 26 and Git for Windows. Keep build tools and logs outside the checkout. The Windows release checkout is ~/Documents/Gitea/learnharness-release-0.5.1, linked to the existing repository in ~/Documents/Gitea/learnharness.

In PowerShell, stop after any failed command:

npm.cmd ci
$env:NODE_ENV = 'test'
$env:ELECTRON_RUN_AS_NODE = '1'
node node_modules/electron/cli.js --import tsx --test tests/pdf-native-render.test.ts tests/pdf-ops.test.ts tests/svg-native-render.test.ts tests/browser-service.test.ts
Remove-Item Env:ELECTRON_RUN_AS_NODE
node --import tsx --test tests/i18n.test.tsx
Remove-Item Env:NODE_ENV
node node_modules/next/dist/bin/next build
node scripts/smoke-provider-runtime.mjs
node scripts/build-server.mjs
node scripts/smoke-server.mjs --electron
node node_modules/electron-builder/out/cli/cli.js --config electron-builder.gitea.yml --win --x64 --publish never
node scripts/gitea-release.mjs verify-package dist/win-unpacked
node scripts/smoke-provider-runtime.mjs --standalone dist/win-unpacked/resources/server/standalone
node scripts/smoke-provider-runtime.mjs --standalone dist/win-unpacked/resources/server/standalone --runtime dist/win-unpacked/LearnHarness.exe
node scripts/smoke-demo-runtime.mjs --standalone dist/win-unpacked/resources/server/standalone --runtime dist/win-unpacked/LearnHarness.exe --browser

Windows contributes three attachments:

• LearnHarness-0.5.1-x64-setup.exe
• LearnHarness-0.5.1-x64-setup.exe.blockmap
• latest.yml

The combined release has seven attachments, including one SHA256SUMS covering all six other files. Verify that latest.yml names the Windows installer exactly, reports version 0.5.1, and matches the installer's actual size and SHA-512. Its gzip blockmap must cover the installer and match every block checksum. Confirm the packaged resources/app-update.yml uses the Gitea generic provider. Windows builds follow upstream's unsigned, per-user installer configuration.

Preparing a Linux-only Gitea draft

Commit and push the release source, then push its exact annotated tag:

git tag -a v0.5.1 -m 'LearnHarness 0.5.1'
git push gitea main v0.5.1

Supply GITEA_TOKEN only to the upload command. A token file may remain outside the clean build checkout:

node --env-file=/path/to/private/release.env scripts/gitea-release.mjs upload dist

The tool requires the tag to exist in Gitea, creates or reuses one draft at that tag, uploads missing assets, and downloads every attachment to verify its actual SHA-256 against the local verified build. Existing mismatched attachments and published releases are refused. It never publishes or changes repository visibility. Release notes come from docs/release-0.5.1.md.

This uploader and its remote verifier enforce a Linux-only inventory. They will refuse a combined Linux/Windows draft. For the combined 0.5.1 release, add the verified Windows attachments to the existing draft and replace SHA256SUMS with the combined manifest. Keep the Linux installers and feed unchanged. Check all seven attachment names, sizes, and actual downloaded hashes against the verified local builds; update the bilingual release notes to include Windows. Do not publish until both platforms' checks pass.

A separate verification can be repeated without changing the draft:

node --env-file=/path/to/private/release.env scripts/gitea-release.mjs verify-remote dist

Review the verified draft before publication. Only after publication will the public latest feed and in-app automatic updates expose this version.

Gitea Actions

.gitea/workflows/release.yml provides the same Linux gates through a manual workflow with an existing release tag as input. It requires a native Linux x64 runner labeled ubuntu-24.04, the label used by upstream's Linux release job, plus the native Electron dependencies and xvfb-run. There were no runners registered when 0.5.1 was prepared, so its packages are built locally. A tag push does not queue a job that cannot run.

The workflow uses the repository's ephemeral GITEA_TOKEN with release-write permission only in the final upload step. It checks out the requested tag without persisting credentials and leaves the result as a verified draft. Public pull requests cannot trigger this publishing workflow. This workflow remains Linux-only; the combined 0.5.1 draft was assembled from local native builds. Windows has its own standalone payload and smoke checks, as described above.