learnharness/docs/gitea-release.md

Gitea releases for this fork

The release destination is https://git.sorokin-oleg-edu.xyz/replicated/learnharness. Version 0.6.1 is Linux x64 AppImage-only; follow the dedicated procedure below. The historical 0.6.0 release 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://git.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.

0.6.1: Linux x64 AppImage-only upload and verification

This release has exactly three attachments:

• LearnHarness-0.6.1-x86_64.AppImage
• latest-linux.yml
• SHA256SUMS

No Windows, macOS, Debian (.deb), or RPM packages belong in this release. Use docs/release-0.6.1.md for the release notes. The procedures below this section retain the historical 0.6.0/full-release instructions; do not use their Debian/Windows asset inventory for 0.6.1.

Stage only the three listed files for upload. Before upload, generate and verify checksums using the existing helper's explicit offline AppImage-only mode:

node scripts/gitea-release.mjs checksums dist --appimage-only
node scripts/gitea-release.mjs verify dist --appimage-only

Run these commands from the 0.6.1 source checkout. They validate the AppImage, feed version, filename, size, SHA-512, and SHA-256 manifest. SHA256SUMS must cover only the AppImage and latest-linux.yml. The offline verifier checks the expected files, not the absence of unrelated files: separately check that the upload selection contains exactly the three names above. Confirm the packaged resources/app-update.yml has the generic provider and the current update URL shown above before uploading.

The unchanged desktop:release:linux script still builds AppImage and Debian packages, so do not use it or the historical manual Actions workflow for this AppImage-only release. Package explicitly with:

electron-builder --config electron-builder.gitea.yml --linux AppImage --x64 --publish never

After building and verifying the copied server/runtime, verify the embedded updater with node scripts/gitea-release.mjs verify-package dist/linux-unpacked. The helper uses the current host and accepts --appimage-only for checksums, verify, upload, and verify-remote; omitting this flag retains the historical AppImage-plus-Debian inventory. Supply GITEA_TOKEN privately for API operations:

node scripts/gitea-release.mjs upload dist --appimage-only
node scripts/gitea-release.mjs verify-remote dist --appimage-only

The uploader creates or reuses a draft and verifies downloaded attachment bytes; it does not publish the release. Publication is a separate explicitly authorized API action after these checks pass.

After the release tag v0.6.1 exists at the intended source commit in the current Gitea repository, create or review a draft for that tag on git.sorokin-oleg-edu.xyz. Set its notes from docs/release-0.6.1.md and explicitly upload only the three listed files. Before publication:

1. Confirm the draft tag is v0.6.1 and its attachment inventory is exactly the three names above, with sizes matching the locally verified files.
2. Download those three draft attachments into a separate directory and run node scripts/gitea-release.mjs verify /path/to/downloaded-assets --appimage-only from the 0.6.1 source checkout. Compare the downloaded SHA256SUMS byte-for-byte with the locally verified manifest; stop on any mismatch.
3. Review the notes and asset exclusions. Publication is a separate, explicitly authorized action; a draft does not update installed clients.

After authorized publication, confirm the current host's public releases/download/latest/latest-linux.yml resolves to version 0.6.1 and references LearnHarness-0.6.1-x86_64.AppImage with the verified size and SHA-512.

Historical 0.6.0 / full-release instructions

The following commands and asset inventories are retained for reference. Their upload tooling still defaults to the old host; they are not the current 0.6.1 upload procedure.

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.6.0 has these attachments:

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

Preparing Windows packages

Use a clean checkout of the same v0.6.0 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.6.0, 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.6.0-x64-setup.exe
• LearnHarness-0.6.0-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.6.0, 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.6.0 -m 'LearnHarness 0.6.0'
git push gitea main v0.6.0

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.6.0.md.

This uploader and its remote verifier enforce a Linux-only inventory. They will refuse a combined Linux/Windows draft. For the combined 0.6.0 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 and sizes against the verified local builds. For the owner-approved 0.6.0 release, local installer/feed/blockmap validation and the combined checksum manifest are completed before upload. Confirm successful upload responses and publish immediately afterward; do not download attachments again or run post-upload hash checks. Do not publish until both platforms' local 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.6.0 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.6.0 draft was assembled from local native builds. Windows has its own standalone payload and smoke checks, as described above.