For developers · Start here
Release
On this page
- Assets
- Apple silicon only (decision 2026-11-16)
- Windows: MSIX and setup (decision 2026-11-16)
- Homebrew (prepared, not published)
- App identifier (decision 2026-11-16, #595)
- Credentials (names only, never in files or logs)
- Ship
- What CI covers
- Releasing with fastlane
- GitHub release from main
- Build
- Windows publisher check
- Verify (before publishing)
- Verified: 0.1.0 at 7c7d883 (2026-11-16)
- Verified: Windows one-liners (2026-11-16, #564)
- Website and documentation
- The docs version
- What the docs are built from
- Custom domain (gitoodo.com)
- Pre-launch site
- Publish (only after the maintainer's release approval, #153)
- releases.json
- Rolling back
How a Gitoodo release is built, checked and published (#152, #153, #562, #564). Users download an installer; building from source stays the fallback for people who want it.
Assets#
All files land in target/release/dist/ on the Mac (the Windows files are copied there).
| File | For | Signing |
|---|---|---|
Gitoodo-<version>-macos-arm64.dmg | Download button, macOS 11+ on Apple silicon | Developer ID, notarized, stapled (DMG and app) |
Gitoodo-macos-arm64.zip | install.sh (one-line install and update) | the same notarized, stapled app |
Gitoodo-<version>-windows-x64.msix | Download button once signed, Windows 10 2004+/11 x64 (per-user MSIX) | MSIX signature; publisher = certificate subject |
Gitoodo.appinstaller | MSIX with automatic updates (always names the newest MSIX) | – (Windows checks the MSIX's signature) |
Gitoodo-<version>-windows-x64-setup.exe | Windows 10/11 x64 per-user NSIS setup, no admin; download button while the MSIX is unsigned | Authenticode when a certificate is set up, else unsigned |
gitoodo-aarch64-apple-darwin | Remote Macs (#441, crates/core/src/remote_version.rs) | Developer ID, notarized (no staple for bare binaries) |
install.sh, uninstall.sh | One-line install and removal on macOS | – |
install.ps1, uninstall.ps1 | One-line install and removal on Windows (MSIX or setup) | – (install.ps1 checks the publisher) |
*.sha256 | shasum -a 256 format (<hash> <file>) | – |
releases.json | Landing page download switch (schema below) | – |
The names of the installers match what the landing page accepts (site/src/release.ts: a .dmg
for macOS; a -setup.exe, .msi or .msix for Windows). The unversioned zip keeps releases/latest/download/... working for
install.sh. Linux CLI assets for remote machines (gitoodo-x86_64-unknown-linux-gnu,
gitoodo-aarch64-unknown-linux-gnu) need a Linux build host and are not produced yet.
Apple silicon only (decision 2026-11-16)#
Gitoodo for macOS ships for Apple silicon (aarch64-apple-darwin) only; there are no Intel
(x86_64-apple-darwin) or universal builds. Reasons: macOS 27 is the last macOS for Intel Macs
and Rosetta 2 ends with macOS 28, so macOS 27 already warns ("App-Update erforderlich") when an
app starts Intel code on Apple silicon; and there is no Intel Mac to test on. What this means:
release-mac.shbuilds and checks (lipo -archs=arm64for every binary in the bundle) the arm64 app and CLI only;deny.tomllists no Intel Mac target.install.shrefuses a Mac without Apple silicon; it askssysctl hw.optional.arm64, so a Terminal running under Rosetta still counts as Apple silicon.- Remote machines (
remote_version.rs,satellite_host.rs) detect the system the same way (uname -sm, corrected bysysctlon macOS). An Intel Mac gets the sourceintel_mac: the settings explain it (hosts.versionIntelMac) and offer no install, and nothing is downloaded. - To check a build, use
lipo -archs; never run an x86_64 binary on an Apple silicon test Mac (it triggers the Rosetta warning there). - Windows stays x64.
Windows: MSIX and setup (decision 2026-11-16)#
Windows gets both, packed by release-windows.ps1 from the same signed binaries:
- MSIX (
src-tauri/windows/AppxManifest.direct.template.xml) is the main download once a signing certificate exists. Per user, no admin; Windows removes the package with all its files, links and thegitoodoalias cleanly; updates come fromGitoodo.appinstaller(checked on launch, every 24 h and in the background;install.ps1registers it); the publisher is shown and checked by Windows itself. - Setup (per-user NSIS) stays: an MSIX installs only when signed by a certificate the machine
trusts, so until the Windows certificate exists the unsigned setup (SmartScreen warning) is the
only installer for normal users; it also runs on Windows 10 before 2004 and where sideloading of
packages is blocked by policy.
releases.jsonoffers the setup first as long as the MSIX is unsigned.
What the direct MSIX needs, and how it is solved:
| Need | Solution |
|---|---|
| One set of settings, logs, tokens | Write virtualization off (desktop6:FileSystemWriteVirtualization/RegistryWriteVirtualization = disabled, capability unvirtualizedResources, Windows 10 2004+): the app, the CLI and the services use the same %APPDATA%/%LOCALAPPDATA% folders as the setup install. Credential Manager is never virtualized. |
| Background services | Unchanged: gitoodo service install copies the CLI to %LOCALAPPDATA%\de.gitoodo.app\bin (outside the package) and registers the scheduled task Gitoodo\Daemon that runs that copy. Updates of the package do not touch it; the app refreshes the copy on launch (#529). |
gitoodo on the PATH | Second application Cli with the execution alias gitoodo.exe (console subsystem) in %LOCALAPPDATA%\Microsoft\WindowsApps. |
| Start at sign-in | The manifest's GitoodoStartup startup task; the direct build uses it when it runs packaged (src-tauri/src/packaged.rs, autostart.rs). A Run entry would name a versioned folder in WindowsApps that the next update removes. |
| Notifications | Packaged, the direct build posts through the package identity (notify_windows.rs), like the store build. |
| Updates | Gitoodo.appinstaller names releases/download/v<version>/Gitoodo-<version>-windows-x64.msix and lives at releases/latest/download/Gitoodo.appinstaller; a newer package must carry the same publisher. The in-app update check still links to the release page. |
| Uninstall | Settings → Apps removes the package but cannot run anything first (MSIX has no uninstall hooks): a registered background service, settings and tokens stay. uninstall.ps1 removes the package (Remove-AppxPackage) and all of that, and checks for leftovers. |
Identity: de.gitoodo.app (the store build has its own Partner Center identity; both can
be installed side by side and share the data of the direct build only through the unvirtualized
folders). Switching between MSIX and setup with install.ps1 -Package removes the other install
first and keeps settings, tokens and services.
Checked on a Windows 11 x64 PC (2026-11-16) with a self-signed test certificate, removed
afterwards: release-windows.ps1 -SignCommand … builds a signed setup and a signed MSIX (both
binaries inside signed; MakeAppx accepts the manifest); install.ps1 with the local MSIX checks
checksum and publisher and installs it; gitoodo --version runs through the alias; gitoodo service install from the packaged command puts the stable copy into the real
%LOCALAPPDATA%\de.gitoodo.app\bin and starts Gitoodo\Daemon; Credential Manager is
read from the package (token-access → readable); the app runs with its package identity and
writes only to the real data folders (nothing in the package's LocalCache); the App Installer
file registers its update settings; switching MSIX → setup → MSIX keeps services, settings and
tokens; uninstall.ps1 removes all of it and -Check finds nothing. Not checked: the startup
task and notifications in the UI, an update from a newer .appinstaller over HTTPS.
Add-AppxPackage needs an interactive sign-in session (over SSH it fails with 0x80070005).
Homebrew (prepared, not published)#
packaging/homebrew/gitoodo.rb is a cask template in the usual style of a project's own tap: the versioned
DMG URL, livecheck on the latest GitHub release, Apple silicon and macOS 11 as requirements,
the gitoodo command as binary, uninstall launchctl: for the LaunchAgents and a zap list.
Publishing it means a tap repository silvio-l/homebrew-gitoodo (brew install --cask silvio-l/gitoodo/gitoodo) and, per release, version and sha256 from releases.json
(downloads.mac); brew style passes on the template. A winget manifest (InstallerType: msix)
can follow once the MSIX is signed.
App identifier (decision 2026-11-16, #595)#
Gitoodo is de.gitoodo.app on every system: bundle ID, keychain group Q7V3X27S2U.de.gitoodo.app,
service helper de.gitoodo.app.service, launchd labels de.gitoodo.app.{daemon,dispatcher},
folders, MSIX identity and AUMID, test build de.gitoodo.app.testaccess. It is written once per
language: app_identifier! in crates/core/src/paths.rs (Rust derives labels, groups and paths
from it), identifier in src-tauri/tauri.conf.json (Tauri, package.ps1, release-windows.ps1,
build-local-mac.sh), and the identifier variables of the install and uninstall scripts. Files
that cannot derive it (Info.plists, entitlements, LaunchAgents, cask) are held equal by
scripts/check-identifier.py in the gates and src-tauri/src/identity_files.rs; the gate also
fails on any identifier built from a person's name.
Gitoodo 0.1.x used online.lindstedt.gitoodo. The first start of a newer direct build moves
everything once (crates/core/src/identity_migration.rs): it stops and removes the old login
items/LaunchAgents (Windows: scheduled tasks, Linux: user units), moves settings, state, logs, web
data and the stable CLI copy (a rename; when the new folder already exists, entry by entry, never
overwriting), copies the keychain tokens from the old access group into the new one, reads them back
and only then deletes the old items, and registers the services again under the new labels with
their previous on/off state. It is idempotent and safe to interrupt; it logs what it moved, never a
value. The CLI moves the folders on service, status, doctor and diagnose for headless
installs. Not moved: preferences and caches (rebuilt), the store and test builds. uninstall.sh,
uninstall.ps1 and the cask remove both identifiers' leftovers. The App Installer of a 0.1.x MSIX
cannot update across identities: such installs update by running install.ps1 again, which installs
the new package and removes the old one (write virtualization is off, so no data goes with it).
Credentials (names only, never in files or logs)#
- macOS signing: the "Developer ID Application" identity of team
Q7V3X27S2Uin the login keychain (APPLE_SIGNING_IDENTITYpicks one when there are several). - macOS keychain profiles (#594, docs/permissions.md "Keychain"):
src-tauri/profiles/direct.provisionprofile(App IDde.gitoodo.app) andsrc-tauri/profiles/service.provisionprofile(App IDde.gitoodo.app.service), both Developer ID. With both, the build adds the service helper so the background services read tokens without a prompt; without them the release script warns. - macOS notarization: an App Store Connect API key,
APPLE_API_KEY(key id),APPLE_API_ISSUER(issuer id) and the key file~/.appstoreconnect/private_keys/AuthKey_<id>.p8(APPLE_API_KEY_PATHoverrides the path). When neither variable is set,release-mac.shandship.shreadASC_KEY_IDandASC_ISSUER_IDfrom~/.appstoreconnect/asc_config(plainNAME=valuelines, the convention of fastlane-style setups;APPLE_ASC_CONFIGoverrides the path). The file is read, never sourced, and its values are never printed; the environment always takes precedence. - Windows signing (optional for the setup, required for a usable MSIX): whatever the
-SignCommandofrelease-windows.ps1needs, e.g. Azure Artifact Signing (formerly Trusted Signing) throughtrusted-signing-cliwithAZURE_CLIENT_ID,AZURE_CLIENT_SECRET,AZURE_TENANT_ID, or a certificate in the Windows store forsigntool. The MSIX publisher is read from the signed app (or-MsixPublisher); it must equal the certificate subject. - Publishing: a GitHub token with
contents: writeonsilvio-l/gitoodo(only for the last step). - Microsoft Store upload (
fastlane windows_store): a Partner Center (Microsoft Entra) app with tenant id, seller id, client id and client secret, stored once withmsstore reconfigure(in CI from secrets); never infastlane/.env.
Ship#
scripts/ship.sh runs the whole release on the Mac, phase by phase, and is the checklist below. It
is internal tooling (it drives the internal forge and the public export) and not part of the public
source; the public pieces it uses are the scripts named in this document and
.github/workflows/deploy-pages.yml.
bash scripts/ship.sh --check # preconditions only; lists every missing piece
bash scripts/ship.sh --prepare --version X.Y.Z # PR to dev: version X.Y.Z, dated CHANGELOG section
bash scripts/ship.sh --dry-run # every phase, read-only checks real, changes printed
bash scripts/ship.sh # the release; stops before publish without approval
bash scripts/ship.sh --approve "Release gitoodo freigegeben" # continues with publishEach phase is recorded in target/ship/<version>/state (a dry run in .../dry-run/state); a
rerun resumes after the last finished phase, --from <phase> repeats a phase and all after it,
--only <phase> runs one, --status shows the state. Settings (Windows host, notary key id,
signing command, ...) come from the environment or ~/.config/gitoodo/ship.env; tokens only from
the keychain or the environment, never from that file, and nothing secret is printed. The script
header lists every variable. bash scripts/ship.test.sh checks the script with fake tools (phase
order, resume, refusals).
- preflight: on
dev, clean, equal toorigin/dev;origin/mainan ancestor (fast-forward possible); CI green on HEAD; one versionX.Y.Zin the Cargo workspace, every crate (the CLI included),Cargo.lock,package.json,package-lock.jsonandsrc-tauri/tauri.conf.json;CHANGELOG.mdhas## [X.Y.Z] - YYYY-MM-DD, no pending "Unreleased" entries, no version heading twice and no subheading (### Added, ...) twice within a section; Developer ID identity, notary key accepted bynotarytool, Rust target, both Developer ID profiles; Windows build host reachable over ssh with a clean checkout, signing command set (or unsigned allowed); GitHub repo writable, Pages source "GitHub Actions", no published releasevX.Y.Z; export configuration present; tools. With--with-storealso the App Store profile, the "Apple Distribution" and "3rd Party Mac Developer Installer" identities, MakeAppx and the Partner Center identity. - gates:
GATES_FULL=1 bash scripts/ci-gates.shand the export dry run with--buildon the release commit; both must be clean. This is the only place before publishing where every gate is sure to run (see "What CI covers" below). - release-pr: branch
release/vX.Y.Zat the release commit (dev's HEAD, sodevmay move on) and its PR →mainon the internal forge. It is merged only in publish, becausemainis exported every night. - tag: annotated
vX.Y.Zon the release commit, local until publish. - build-mac:
release-mac.shin a worktree at the release commit (profiles copied in); thenspctlandstapleron the DMG and the zipped app,codesign --verify --deep --strict,lipo -archs=arm64, the app version, the checksums. - build-windows:
release-windows.ps1on the Windows host at the release commit over ssh; everyGitoodo-X.Y.Z-windows-*asset it writes (with its.sha256) is copied back; checksum and Authenticode status (Valid, the expected signer) checked. - store-mac, store-windows (optional,
--with-store): the Mac App Store pkg (scripts/build-appstore-mac.sh, store, "Submission build") and the store MSIX (src-tauri/windows/package.ps1with the Partner Center identity). They are not GitHub assets; the uploads stay manual. - manifest: every
.sha256checked,release-manifest.py,releases.jsonchecked (version, macOS signed and notarized, Windows present and signed), release notes from the CHANGELOG. - site:
GITOODO_SITE_RELEASES=<dist>/releases.json bash scripts/release-site.sh vX.Y.Z: the tagged site with download buttons, docs version, link check;releases.jsonbeside the page. - publish, only with the exact phrase "Release gitoodo freigegeben" (asked, or
--approve); without it the script stops with exit code 4 and nothing public has happened: push the tag internally; merge the release PR fast-forward-only withhead_commit_id; exportmainand then the tag to GitHub (each as a plan run first); create the GitHub release as a draft, upload every file of the dist folder, compare the asset list, publish it as latest; dispatchdeploy-pages.ymlfor the tag and wait for it; print the store upload steps. - verify: download every public asset and compare it byte for byte;
releases/latestnames the version;spctlandstapleron the downloaded DMG;curl -fsSL <site>/install.sh | GITOODO_VERIFY_ONLY=1 bash(downloads and checks checksum, signature and Gatekeeper, installs nothing); the live page links both installers, every URL inreleases.jsonanswers 200, the install scripts equal the release's, the docs carry the tag; on the Windows host the setup's hash and signature. - bump: PR to
devwith the next version asX.Y.(Z+1)-dev(--nextpicks another) and a new empty "Unreleased" section.
The Pages workflow builds the tag with the release's releases.json through the same
release-site.sh; it runs only when dispatched, so merges never change the live site.
What CI covers#
- **Internal forge,
gate/nas** (.forgejo/workflows/gate.yml, on every pull request and push todev): only the cheap gates. Its runner image has neither npm nor cargo, soscripts/ci-gates.shruns the allowlist, typos and script tests and printsSKIPPED:for the Node gates (Prettier,tsc, ESLint, Knip, Vitest, builds) and the Rust gates (fmt, clippy, tests, machete, deny); gitleaks and shellcheck run as well. The status then reads "cheap gates green; Node/Rust gates SKIPPED". A greengate/nastherefore does not mean the code builds. - **
lab/ubu,lab/win**: not set up for gitoodo yet (nolab.yml), so no such status exists. - GitHub CI (
.github/workflows/ci.yml): every Node and Rust gate on Linux, but only on the exportedmainand on public pull requests, i.e. after the release has been merged.
Before a release, GATES_FULL=1 bash scripts/ci-gates.sh must pass locally on the release commit
(a missing tool fails instead of being skipped); ship.sh runs exactly that in its gates
phase and stops when it fails. Run it yourself before merging larger changes to dev.
Releasing with fastlane#
fastlane drives the steps that talk to Apple, GitHub and the Microsoft
Store. It does not replace the scripts: the lanes call release-mac.sh (build, Developer ID,
notarization with notarytool), build-appstore-mac.sh, release-manifest.py and
release-check.py, so a release built by hand, by ship.sh or by a lane is the same. Every lane
works in a fork: no fixed paths or accounts, configuration from the environment or the
git-ignored fastlane/.env (template: fastlane/.env.example; names and IDs only, never key
contents or tokens).
bundle install # once: fastlane from the Gemfile (Ruby 3.2+)
bundle exec fastlane check # prerequisites, read-only
bundle exec fastlane mac direct dry_run:true # any lane: checks run, changes are only printed| Target | Lane | Prerequisites |
|---|---|---|
| Direct download, macOS | fastlane mac direct | Developer ID Application identity; App Store Connect API key (APPLE_API_KEY, APPLE_API_ISSUER or the asc_config, key file); direct/service profiles (GITOODO_PROFILES_DIR or fastlane mac profiles) |
| Direct download, Windows | none: scripts/release-windows.ps1 on Windows | Windows build host, signing command; copy its Gitoodo-<version>-windows-* files, Gitoodo.appinstaller and their .sha256 into target/release/dist/ |
| GitHub release (draft) | fastlane github_stage | gh auth login (or GITHUB_TOKEN) with contents: write; the complete target/release/dist/; GITOODO_GITHUB_REPO for a fork |
| GitHub release (publish) | none: .github/workflows/release.yml | the release tag vX.Y.Z on main of the GitHub repository (see below) |
| Mac App Store | fastlane mac store (upload:true, submit:true) | "Apple Distribution" and "3rd Party Mac Developer Installer" identities; App Store profile for de.gitoodo.app; App Store Connect record; the API key with the App Manager role |
| Provisioning profiles | fastlane mac profiles (create:true) | the API key; the App IDs de.gitoodo.app and de.gitoodo.app.service in the developer account |
| Microsoft Store | fastlane windows_store msix:<path> (upload:true, submit:true) | msstore CLI (macOS, Linux or Windows), configured once with msstore reconfigure; MSSTORE_PRODUCT_ID; the store MSIX from src-tauri/windows/package.ps1 |
What each lane changes, and what not:
mac directwritestarget/release/dist/(the same asbash scripts/release-mac.sh). The notarization stays in the script (onenotarytoolsubmission for app and CLI, one for the DMG); fastlane'snotarizeaction would only duplicate it.github_stagerefreshesreleases.json, checks the folder withrelease-check.py dist(every file ofreleases.json'sassetspresent, sizes and SHA-256 equal, every.sha256matching, no extra file, URLs on the tag), creates the releasevX.Y.Zas a draft with the CHANGELOG section as notes, uploads every file and compares the list. A draft is visible only to the repository's maintainers; the lane refuses a release that is already published. fastlane'sset_github_releasecannot update a draft or mark the latest release, so the lane usesgh.mac storebuilds the package; onlyupload:trueuploads it to App Store Connect (deliver, build only:skip_metadata,skip_screenshots), and onlysubmit:truesubmits it for review. It refuses whensrc-tauri/tauri.conf.jsonand the Appfile name different identifiers.windows_storechecks that the MSIX carries the release version;upload:truerunsmsstore publish --noCommit(the package lands in a Partner Center draft submission),submit:truecommits it for certification. fastlane has no Microsoft Store support of its own; the third-partysapfireplugin runs on Windows only, Microsoft'smsstoreCLI also on the Mac. The first submission of the app is made by hand in Partner Center.mac profilesdownloads the profiles read-only (sigh);create:truecreates missing ones in the developer account.
GitHub release from main#
.github/workflows/release.yml publishes the release when its tag vX.Y.Z arrives on the
GitHub repository (or when started by hand with the tag). Here the tag only arrives through the
export after the release approval: the release commit is merged into main, main and then the
tag are exported (see Ship, publish). The workflow builds and signs nothing; it
- checks that the tag is on
main, that the Cargo workspace,package.jsonandtauri.conf.jsoncarry the version and thatCHANGELOG.mdhas its section (release-check.py tree); - waits (up to 60 minutes) until the release
vX.Y.Zlists every file named in itsreleases.json(staged bygithub_stageor byship.sh), downloads all of them and runsrelease-check.py dist; a missing, extra or changed file fails the run and nothing is published; - sets the CHANGELOG section as notes and publishes the draft, as the latest release unless a
newer version is already published; checks that
releases/latest/download/releases.jsonnames the version and startsdeploy-pagesfor the tag.
A release that is already published (e.g. by ship.sh) is only checked again, so a rerun is safe.
It needs no secret beyond the workflow's own token (contents: write, actions: write). For a
second gate, add required reviewers to the github-release environment in the repository
settings.
Order of a release with fastlane: mac direct → Windows assets into the dist → github_stage
(draft) → approval → tag and main on GitHub → the workflow publishes. The store lanes run
after the approval, independently of GitHub.
Build#
macOS (Apple silicon Mac, Xcode command line tools, Python 3):
rustup target add aarch64-apple-darwin
npm ci
export APPLE_API_KEY=… APPLE_API_ISSUER=… # from your App Store Connect key (or ~/.appstoreconnect/asc_config)
bash scripts/release-mac.shIt refuses a bundle from another commit than HEAD or with any non-arm64 code, builds the app
with the CLI, signs and notarizes the app and the CLI binary in one submission, staples the app, zips it, builds
the DMG with dmgbuild (a pinned copy in target/dmgbuild-venv; it writes the Finder layout
itself, so no Finder window opens), signs, notarizes and staples the DMG, writes the checksums and
releases.json. About 10–20 minutes, most of it the release compile and notarization.
Windows (any Windows 10/11 x64 with Node, the Rust MSVC toolchain and the C++ build tools; Tauri fetches NSIS itself), PowerShell in the repository root:
npm ci
./scripts/release-windows.ps1 # unsigned release candidate
./scripts/release-windows.ps1 -SignCommand '…%1' # signed (see the script header)It builds the setup, then packs the same binaries as Gitoodo-<version>-windows-x64.msix
(src-tauri/windows/package.ps1 -Variant direct, Windows SDK MakeAppx), signs it with the same
command and writes Gitoodo.appinstaller (-ReleaseBase changes its links, e.g. for a local test
server). -NoMsix skips the MSIX. Copy every file of target\release\dist\ (with the
.sha256 files) into the Mac's target/release/dist/, then rerun
python3 scripts/release-manifest.py there; it checks every .sha256 against its file, checks
that the .appinstaller names this release's MSIX and records the signature state.
Windows publisher check#
install.ps1 installs only a setup whose SHA-256 matches downloads.windows.sha256 in
releases.json and whose Authenticode signature is Valid and names the expected publisher
($GitoodoSigner in the script, overridable with -Signer/GITOODO_SIGNER; a certificate
thumbprint can be pinned with -Thumbprint/GITOODO_SIGNER_THUMBPRINT). After the setup it also
checks that gitoodo.exe carries the same signature. $GitoodoSigner is a placeholder
(Silvio Lindstedt) until the Windows certificate exists: once it does, set it to the
certificate's subject CN ((Get-AuthenticodeSignature <setup>).SignerCertificate.GetNameInfo('SimpleName', $false))
and pin it in the marked TODO(signing) constants: $GitoodoSignerThumbprint (SHA-1 thumbprint,
.SignerCertificate.Thumbprint) and $GitoodoSignerIssuer (the issuing CA's CN,
.SignerCertificate.GetNameInfo('SimpleName', $true)); both stay empty until the certificate
exists, then a matching name also needs that issuer. Unsigned setups (today's release candidates)
need -AllowUnsigned/GITOODO_ALLOW_UNSIGNED=1; without it the script stops with both ways on
(the download with SmartScreen's "More info → Run anyway", or the opt-in), and the site shows the
SmartScreen hint instead of the PowerShell line while downloads.windows.signed is false. A
broken or foreign signature is refused even then.
The DMG background is scripts/dmg/background.tiff (1x and 2x), rendered from the brand lockup
by scripts/dmg/make-background.sh; the icon positions live in scripts/dmg/settings.py.
scripts/dmg/build-dmg.sh <app> <dmg> builds the image (release-mac.sh uses it) and runs
scripts/dmg/check-dmg.sh, which mounts it read-only and hidden and requires the app, the
Applications link, the background picture and the icon positions of settings.py. Both work on
an unsigned local bundle for a layout check; nothing is opened.
Verify (before publishing)#
macOS, on a machine without Gitoodo (the MacBook test machine):
- Copy the DMG over (
scpsets no quarantine flag; add it to act like a browser download:xattr -w com.apple.quarantine "0081;$(printf %x $(date +%s));Safari;" <dmg>). hdiutil attach, copyGitoodo.appto/Applications,hdiutil detach.lipo -archsonContents/MacOS/*→arm64;spctl -a -vv /Applications/Gitoodo.app→accepted,source=Notarized Developer ID;xcrun stapler validateon the app and the DMG →The validate action worked!.- Open the app once: no Gatekeeper dialog other than the usual "downloaded from the internet" confirmation; the onboarding appears. Quit it.
bash scripts/uninstall.sh --keep-repos(or the published one-liner), then--checkreports nothing left.
Windows, on a Windows 11 test machine: run the setup (per-user, installs to %LOCALAPPDATA%\Gitoodo), launch from
the Start menu, set up the background service from the app, quit, uninstall from Settings → Apps;
the "Gitoodo" entry, the install folder, the shortcuts and the Gitoodo\Daemon task are gone (the
uninstaller runs gitoodo service uninstall classifier; app data in
%LOCALAPPDATA%\de.gitoodo.app stays, as usual for NSIS). An unsigned setup shows
SmartScreen's "Windows protected your PC" for files with the internet zone mark. Run
gitoodo service install from the desktop session, not over ssh: OpenSSH sets
USERDOMAIN=WORKGROUP, and schtasks cannot map WORKGROUP\<user>.
The one-liners, against a locally served asset set (no published release needed): put the setup,
releases.json, install.ps1 and uninstall.ps1 in a folder, serve it with
python -m http.server 8765 --bind 127.0.0.1, then
$env:GITOODO_RELEASE_URL = 'http://127.0.0.1:8765'; $env:GITOODO_ALLOW_UNSIGNED = '1'
irm http://127.0.0.1:8765/install.ps1 | iex # install; again with a newer setup = update
irm http://127.0.0.1:8765/uninstall.ps1 | iex # remove everything, ends with the leftover checkWithout GITOODO_ALLOW_UNSIGNED the unsigned setup must be refused; a changed sha256 in the
manifest must be refused too. GITOODO_SETUP=<path to setup.exe> installs a local file instead
(its releases.json or .sha256 must lie beside it).
Verified: 0.1.0 at 7c7d883 (2026-11-16)#
- macOS (MacBook, macOS 27, Apple silicon): DMG and app
accepted(Notarized Developer ID), both stapled,syspolicy_check distributionpassed,lipo -archs=arm64forgitoodo-appandgitoodo, Applications link and background present. The first launch showed only the "downloaded from the internet" confirmation (with "Apple checked it for malicious software"); the onboarding appeared.uninstall.sh --keep-reposand--check: nothing left. - Windows (test machine, Windows 11 x64): the silent setup
/Sinstalled per user (publisher "Silvio Lindstedt", Start menu and desktop link), the app started in the desktop session with the onboarding, the CLI reportedgitoodo 0.1.0. The service installed from the desktop session ran asGitoodo\Daemon; the silent uninstall removed the entry, folder, links, the task and every process. The setup is unsigned.
Verified: Windows one-liners (2026-11-16, #564)#
Against locally served unsigned 0.1.0 and 0.1.1 setups (GITOODO_RELEASE_URL, irm | iex):
refused without GITOODO_ALLOW_UNSIGNED and with a changed sha256; installed 0.1.0 per user with
gitoodo on the user PATH (REG_EXPAND_SZ kept, a new shell finds gitoodo --version); updated to
0.1.1 in place (both CLI copies refreshed, PATH unchanged). In the desktop session the uninstaller
removed the app, the PATH entry, the Gitoodo\Daemon task and its process, a *.gitoodo
credential, the data folders, the links, the manufacturer keys and the skill; -RemoveRepos kept
the clones while one held uncommitted changes and removed them once it was clean; -KeepRepos
kept them; -Check found nothing left. The publisher check of a signed setup waits for the
certificate.
Website and documentation#
Every release rebuilds the website and its docs from the tagged sources, so /docs/ always
describes the released version. bash scripts/release-site.sh vX.Y.Z checks that the tag points at
HEAD and the work tree is clean, builds site/dist with GITOODO_DOCS_VERSION=vX.Y.Z (the
production build, npm run site:build:production), checks every link and anchor
(npm run site:links) and confirms that the docs carry the version. With
GITOODO_SITE_RELEASES=<dist>/releases.json the page gets the release's download buttons
(site/releases.json is written for the build in its short form and restored afterwards) and
site/dist/releases.json is the release's manifest. scripts/release-mac.sh runs it by itself
when HEAD carries v<version>; otherwise it prints the command. It publishes nothing; the
deploy-pages workflow publishes it.
The production build fails while the release it reads says { "release": null } (the checked-in
site/releases.json), so the published page always offers the installers and the one-line install:
run it with GITOODO_SITE_RELEASES (the ship script's site phase, the deploy-pages workflow and
scripts/release-mac.sh once the dist holds both installers do). The site reads the short form as
well as the release manifest itself (site/src/release.ts, a .dmg for macOS and a -setup.exe,
.msi or .msix for Windows), so nothing has to be committed for a release. Every other build
(npm run site:build, CI) is a local preview: without a release it shows a notice in place of the
download buttons.
The docs version#
Every docs page shows the version it was built for, in the header badge, at the end of each page
and as <meta name="docs-version">:
- A release tag (
v1.2.3) whenGITOODO_DOCS_VERSIONis set (byscripts/release-site.sh) or when the checkout is a taggedv*commit. - **
dev** for every other build, with a tooltip naming the release it follows (the version insite/releases.json, otherwisepackage.json).
A release tag that is not of the form vX.Y.Z, or that differs from the version
site/releases.json names, fails the build, so the docs badge and the download section never
disagree. The logic lives in site/src/docs/version.ts.
What the docs are built from#
site/docs/build.ts, called by site/build.ts, generates site/dist/docs/ on every
npm run site:build:
- User pages in all six site languages from the in-app help (
src/views/help/topics.tswith the texts insrc/i18n/), the settings structure (src/views/settings/structure.ts) and the pages written for the web insite/docs/pages/<lang>/(English is always there; a language without its own text shows the English one with a note). - Developer pages in English from the curated documents in
docs/(the list and the reasons for every excluded document are insite/src/docs/registry.ts),site/docs/dev/and the usage text ofgitoodo --help(crates/cli/src/main.rs). - Captures only from
site/shots/.
The build fails on a link to a missing page or anchor. Archived docs of earlier major versions are
not kept; the docs always describe the current release or, for dev builds, the development
branch.
Custom domain (gitoodo.com)#
The website lives at https://gitoodo.com/, the site root (no project path), on GitHub Pages of
silvio-l/gitoodo. The one source is SITE_URL in src/question/specUrl.ts (canonical, hreflang,
og:url, the one-line installs, the question format URL, the app's website and docs links); the
pages link each other with relative paths. www.gitoodo.com redirects to the apex; the former
project address on github.io redirects to the custom domain as long as it is set.
- CNAME: every build writes
site/dist/CNAMEwithgitoodo.com(site/src/domain.ts).npm run site:linksandnpm run site:links:prelaunchfail without it, with another domain in it, or on any link to the former project address ongithub.ioin a text file of the build (thewwwrecord below may name the Pages host).scripts/publish-site-prelaunch.shwrites it into the published commit as well: a branch published withgh-pagestakes its custom domain from that file, and a force-push without it would drop the domain. A site deployed by thedeploy-pagesworkflow (GitHub Actions) takes the domain from the repository's Pages setting instead; the file is harmless there. - DNS (Cloudflare, "DNS only", not proxied, so GitHub can issue and renew the certificate):
apex
gitoodo.comA185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153 andAAAA2606:50c0:8000::153, 2606:50c0:8001::153, 2606:50c0:8002::153, 2606:50c0:8003::153;wwwCNAMEsilvio-l.github.io. - Pages settings: custom domain
gitoodo.com, then "Enforce HTTPS" once GitHub has issued the certificate (gh api --method PUT repos/silvio-l/gitoodo/pages -f cname=gitoodo.com -F https_enforced=true). Verifying the domain for the account (Settings, Pages, "Verified domains") keeps others from claiming it. - Outside this repository: the contact relay must answer the CORS preflight of
https://gitoodo.com(sendergitoodo-web), and the Matomo measurable "Gitoodo Website" must listhttps://gitoodo.com(scripts/matomo/create-gitoodo-site.phpadds it to an existing one);excludeUnknownUrlsdrops hits from any host it does not list.
Pre-launch site#
Before the first release the website can go live on its own, without installers and without the source code: the pre-launch build. It is a deliberate mode, never the fallback of a failed release build.
- Build:
bash scripts/site-prelaunch.sh(=npm run site:build:prelaunch, i.e.node site/build.ts --production --prelaunch;GITOODO_SITE_PRELAUNCH=1does the same as--prelaunch, thennpm run site:links:prelaunch). It only runs whilesite/releases.jsonsays{ "release": null }, withoutVITE_REPO_PUBLIC=1and without a release tag (site/src/release.tssiteRelease,site/src/docs/version.ts).--productionwithout--prelaunchstill fails on{ "release": null }. - What the page shows: no download buttons, no one-line install and no
install.sh/install.ps1beside the page. The download section says that the first release is on its way (in all six languages,sooninsite/src/copy/), and its button and the hero's open the contact form with a short "please let me know" message filled in; without JavaScript they are a mail to the GbR mailbox. The header button and the footer link read "Get notified". No link leads to the repository (source, issues, clone, star, changelog, licence, skill, the question format's source, "Edit on GitHub"); the app's privacy policy and the agent skill link to their docs pages instead. The docs badge readsdevwith the tooltip "Pre-release: Gitoodo has not been released yet", and "Getting started" notes under its install heading that the commands work from the first release on. There is no preview banner. - Contact form: the pre-launch build is a production build, so the form posts as the live
sender
gitoodo-web. The relay must answer the CORS preflight of the page's originhttps://gitoodo.com; on 2026-11-16 it still answered only the former origin of the Pages address (gitoodo.comgot 403), so the form fails until the relay allows it. A message from the live page is a real mail to the team. - Check:
npm run site:links:prelaunch(site/docs/check-prelaunch.ts) fails on any link intogithub.com/silvio-l/gitoodoin any attribute of any page, on any broken internal link or anchor of any page, on installers insite/dist, on a landing page that is not a pre-launch build, and on a missing or wrongCNAMEor a link to the former Pages address (Custom domain). - Publish (only with the maintainer's approval): the repository stays unpublished, so the
deploy-pagesworkflow (it builds from a tag of the repository) cannot be used.bash scripts/publish-site-prelaunch.sh silvio-l/gitoodocheckssite/distagain and prepares one orphan commit with only the built files plus.nojekyllandCNAME(gitoodo.com; anything that looks like source stops it); it is a dry run and pushes nothing.--publishforce-pushes that commit to the branchgh-pages. The script never changes the Pages settings; it prints the call that switches Pages from the workflow to the branch once:gh api --method PUT repos/silvio-l/gitoodo/pages -f build_type=legacy -f 'source[branch]=gh-pages' -f 'source[path]=/'. The site is then athttps://gitoodo.com/. - Side effect on an empty repository: the first pushed branch becomes the default branch, so
github.com/silvio-l/gitoodowould show the built HTML as the repository's code. To avoid that, push amainwith only a short README first (that is publishing too and needs the same approval), thengh-pages; or accept it until the release replaces it. - **Pre-launch
main:** GitHubmainholds a hand-made pre-launch state, not an export: a short README (no download, no source link, "Get notified" via the website's contact form),LICENSE,CODE_OF_CONDUCT.md, a pre-launchCONTRIBUTING.mdandSECURITY.md,.github/FUNDING.ymland the README's images under.github/assets/. No source code, no workflows. It is not kept in this repository; the globalpre-pushhook blocks git pushes to GitHub, so the maintainer pushes it by hand. Repository settings for this phase: Issues, Wiki, Projects and Discussions off, private vulnerability reporting and Dependabot alerts on, squash as the only merge button. - **Pre-launch
mainand the export:**repos/gitoodo.jsonin the export repository setsfirst_export: "reset". As long as the head of publicmaincarries noGitOrigin-RevIdtrailer, every export run (nightly or dispatched) stops with "first export of silvio-l/gitoodo must be the one-time history reset (RESET_HISTORY) — nothing pushed" and exits 0, so the nightly run counts it as done and nothing is published or overwritten. Without any publicmain, the first nightly run would instead export internalmainon its own as a fresh root commit; the pre-launchmaintherefore also guards against an unintended first export. - At the first release: run the one-time history reset of the export on the NAS
(
RESET_HISTORY="RESET silvio-l/gitoodo"forexport-run.sh; never a workflow dispatch). It force-pushes (with lease) one fresh root commit of the exported tree tomain: the exportedREADME.md, community files and.github/(issue and pull request templates, workflows) replace the pre-launch ones, and the pre-launch commit leaves the history ofmain. Later exports are normal incremental syncs. Then switch Pages back to the workflow (gh api --method PUT repos/silvio-l/gitoodo/pages -f build_type=workflow), publish the release site as described below and delete thegh-pagesbranch; asite/releases.jsonwith a release makes the pre-launch build fail from then on. Finally turn Issues on (gh api -X PATCH repos/silvio-l/gitoodo -F has_issues=true; the issue templates arrive with the export) and drop "First release coming soon." from the repository description.
Publish (only after the maintainer's release approval, #153)#
The publish phase of Ship does these steps; by hand they are:
- Push the tag
v<version>of the release commit, merge it intomain, and exportmainand the tag to GitHubsilvio-l/gitoodo. - Create the GitHub release
v<version>as a draft with the notes fromCHANGELOG.md, upload every file oftarget/release/dist/(includingreleases.json,Gitoodo.appinstaller,install.sh,uninstall.sh,install.ps1,uninstall.ps1and all.sha256), compare the uploaded list withassetsinreleases.json, and only then publish it. Until it is published,releases/latest/download/...(the one-liners, the.appinstaller) keeps serving the previous release complete, never a half-uploaded one. - Run the
deploy-pagesworkflow of the GitHub repo for the tag (gh workflow run deploy-pages.yml --ref main -f tag=v<version>): it buildssite/distwithscripts/release-site.shand the release'sreleases.jsonand publishes it (https://gitoodo.com/, Custom domain). - Check from a clean machine: the landing page download,
curl … | bashon a Mac,irm … | iexon Windows, and the download URLs inreleases.json(curl -fIL <url>answers 200).
releases.json#
{
"schemaVersion": 1,
"version": "0.1.0",
"tag": "v0.1.0",
"date": "2026-11-16",
"releaseUrl": "https://github.com/silvio-l/gitoodo/releases/tag/v0.1.0",
"downloads": {
"mac": {
"file": "Gitoodo-0.1.0-macos-arm64.dmg",
"url": "https://github.com/silvio-l/gitoodo/releases/download/v0.1.0/Gitoodo-0.1.0-macos-arm64.dmg",
"size": 0,
"sha256": "…",
"kind": "dmg",
"arch": "arm64",
"minOs": "11.0",
"signed": true,
"notarized": true
},
"windows": { "…": "the same object as windowsMsix or windowsSetup, see below" },
"windowsMsix": {
"file": "Gitoodo-0.1.0-windows-x64.msix",
"url": "https://github.com/silvio-l/gitoodo/releases/download/v0.1.0/Gitoodo-0.1.0-windows-x64.msix",
"size": 0,
"sha256": "…",
"kind": "msix",
"arch": "x64",
"minOs": "10.0.19041",
"signed": true,
"notarized": false,
"appInstaller": {
"file": "Gitoodo.appinstaller",
"url": "https://github.com/silvio-l/gitoodo/releases/latest/download/Gitoodo.appinstaller"
}
},
"windowsSetup": {
"file": "Gitoodo-0.1.0-windows-x64-setup.exe",
"url": "https://github.com/silvio-l/gitoodo/releases/download/v0.1.0/Gitoodo-0.1.0-windows-x64-setup.exe",
"size": 0,
"sha256": "…",
"kind": "nsis",
"arch": "x64",
"minOs": "10",
"signed": false,
"notarized": false
}
},
"macInstallCommand": "curl -fsSL https://gitoodo.com/install.sh | bash",
"macUninstallCommand": "curl -fsSL https://gitoodo.com/uninstall.sh | bash",
"windowsInstallCommand": "irm https://gitoodo.com/install.ps1 | iex",
"windowsUninstallCommand": "irm https://gitoodo.com/uninstall.ps1 | iex",
"assets": [{ "file": "…", "url": "…", "size": 0, "sha256": "…" }]
}downloadsholds one entry per platform (mac,windows), the one offered first; a platform without an installer is absent.windowsis the MSIX when it is signed (or the only Windows file), otherwise the setup;windowsMsixandwindowsSetuplist each format that exists. The landing page readsversion,releaseUrlandurl,size,sha256ofdownloads.macanddownloads.windows(site/src/release.ts) and needs both.sizeis in bytes,sha256lowercase hex.archisarm64(macOS, Apple silicon only) orx64(Windows).minOsis the macOS version (LSMinimumSystemVersion) or the Windows major version.signed/notarizedare checked from the files, not configured; the page may show a hint for an unsigned Windows setup.assetslists every file of the release except the.sha256files and the manifest.GITOODO_RELEASE_BASEchanges the URL base (forks).install.ps1reads<base>/releases.json(defaulthttps://github.com/silvio-l/gitoodo/releases/latest/download, override with-ReleaseUrlorGITOODO_RELEASE_URL) and needsfileandsha256ofdownloads.windows(or ofwindowsMsix/windowsSetupfor-Package msix/setup).
Rolling back#
To go back to an earlier release, install it over the current one; settings, accounts, tokens and the background service stay, as with an update:
- macOS:
curl -fsSL https://gitoodo.com/install.sh | GITOODO_RELEASE_URL=https://github.com/silvio-l/gitoodo/releases/download/vX.Y.Z bash, or the older DMG from that release's page dragged over the app in Applications. - Windows:
$env:GITOODO_RELEASE_URL = 'https://github.com/silvio-l/gitoodo/releases/download/vX.Y.Z'; irm https://gitoodo.com/install.ps1 | iexor the older setup.exefrom the release page. An installed MSIX refuses a lower version; add$env:GITOODO_PACKAGE = 'setup', which removes the MSIX first and keeps settings, accounts and tokens (header ofscripts/install.ps1).
Data compatibility. Every data file in the config folder carries a schema_version, and
migrations only go forward: a newer Gitoodo upgrades the files on its first start, an older one
refuses them unchanged (StoreError::UnsupportedVersion). The app then logs
startup_failed and shows a native dialog ("This Gitoodo (…) is older than your data …", with
the log folder) instead of quitting silently. A rollback across a schema change therefore needs
either the newer version again, or the settings exported before the update (Settings → Backup,
docs/settings-backup.md) imported into a fresh config folder of the older version. Rolling back
between releases without a schema change needs nothing; name schema changes in the release notes.