Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Start here

Release

On this page
  1. Assets
  2. Apple silicon only (decision 2026-11-16)
  3. Windows: MSIX and setup (decision 2026-11-16)
  4. Homebrew (prepared, not published)
  5. App identifier (decision 2026-11-16, #595)
  6. Credentials (names only, never in files or logs)
  7. Ship
  8. What CI covers
  9. Releasing with fastlane
  10. GitHub release from main
  11. Build
  12. Windows publisher check
  13. Verify (before publishing)
  14. Verified: 0.1.0 at 7c7d883 (2026-11-16)
  15. Verified: Windows one-liners (2026-11-16, #564)
  16. Website and documentation
  17. The docs version
  18. What the docs are built from
  19. Custom domain (gitoodo.com)
  20. Pre-launch site
  21. Publish (only after the maintainer's release approval, #153)
  22. releases.json
  23. 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).

FileForSigning
Gitoodo-<version>-macos-arm64.dmgDownload button, macOS 11+ on Apple siliconDeveloper ID, notarized, stapled (DMG and app)
Gitoodo-macos-arm64.zipinstall.sh (one-line install and update)the same notarized, stapled app
Gitoodo-<version>-windows-x64.msixDownload button once signed, Windows 10 2004+/11 x64 (per-user MSIX)MSIX signature; publisher = certificate subject
Gitoodo.appinstallerMSIX with automatic updates (always names the newest MSIX)– (Windows checks the MSIX's signature)
Gitoodo-<version>-windows-x64-setup.exeWindows 10/11 x64 per-user NSIS setup, no admin; download button while the MSIX is unsignedAuthenticode when a certificate is set up, else unsigned
gitoodo-aarch64-apple-darwinRemote Macs (#441, crates/core/src/remote_version.rs)Developer ID, notarized (no staple for bare binaries)
install.sh, uninstall.shOne-line install and removal on macOS–
install.ps1, uninstall.ps1One-line install and removal on Windows (MSIX or setup)– (install.ps1 checks the publisher)
*.sha256shasum -a 256 format (<hash> <file>)–
releases.jsonLanding 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.sh builds and checks (lipo -archs = arm64 for every binary in the bundle) the arm64 app and CLI only; deny.toml lists no Intel Mac target.
  • install.sh refuses a Mac without Apple silicon; it asks sysctl 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 by sysctl on macOS). An Intel Mac gets the source intel_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 the gitoodo alias cleanly; updates come from Gitoodo.appinstaller (checked on launch, every 24 h and in the background; install.ps1 registers 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.json offers the setup first as long as the MSIX is unsigned.

What the direct MSIX needs, and how it is solved:

NeedSolution
One set of settings, logs, tokensWrite 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 servicesUnchanged: 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 PATHSecond application Cli with the execution alias gitoodo.exe (console subsystem) in %LOCALAPPDATA%\Microsoft\WindowsApps.
Start at sign-inThe 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.
NotificationsPackaged, the direct build posts through the package identity (notify_windows.rs), like the store build.
UpdatesGitoodo.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.
UninstallSettings → 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 Q7V3X27S2U in the login keychain (APPLE_SIGNING_IDENTITY picks one when there are several).
  • macOS keychain profiles (#594, docs/permissions.md "Keychain"): src-tauri/profiles/direct.provisionprofile (App ID de.gitoodo.app) and src-tauri/profiles/service.provisionprofile (App ID de.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_PATH overrides the path). When neither variable is set, release-mac.sh and ship.sh read ASC_KEY_ID and ASC_ISSUER_ID from ~/.appstoreconnect/asc_config (plain NAME=value lines, the convention of fastlane-style setups; APPLE_ASC_CONFIG overrides 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 -SignCommand of release-windows.ps1 needs, e.g. Azure Artifact Signing (formerly Trusted Signing) through trusted-signing-cli with AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID, or a certificate in the Windows store for signtool. The MSIX publisher is read from the signed app (or -MsixPublisher); it must equal the certificate subject.
  • Publishing: a GitHub token with contents: write on silvio-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 with msstore reconfigure (in CI from secrets); never in fastlane/.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 publish

Each 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).

  1. preflight: on dev, clean, equal to origin/dev; origin/main an ancestor (fast-forward possible); CI green on HEAD; one version X.Y.Z in the Cargo workspace, every crate (the CLI included), Cargo.lock, package.json, package-lock.json and src-tauri/tauri.conf.json; CHANGELOG.md has ## [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 by notarytool, 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 release vX.Y.Z; export configuration present; tools. With --with-store also the App Store profile, the "Apple Distribution" and "3rd Party Mac Developer Installer" identities, MakeAppx and the Partner Center identity.
  2. gates: GATES_FULL=1 bash scripts/ci-gates.sh and the export dry run with --build on 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).
  3. release-pr: branch release/vX.Y.Z at the release commit (dev's HEAD, so dev may move on) and its PR → main on the internal forge. It is merged only in publish, because main is exported every night.
  4. tag: annotated vX.Y.Z on the release commit, local until publish.
  5. build-mac: release-mac.sh in a worktree at the release commit (profiles copied in); then spctl and stapler on the DMG and the zipped app, codesign --verify --deep --strict, lipo -archs = arm64, the app version, the checksums.
  6. build-windows: release-windows.ps1 on the Windows host at the release commit over ssh; every Gitoodo-X.Y.Z-windows-* asset it writes (with its .sha256) is copied back; checksum and Authenticode status (Valid, the expected signer) checked.
  7. 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.ps1 with the Partner Center identity). They are not GitHub assets; the uploads stay manual.
  8. manifest: every .sha256 checked, release-manifest.py, releases.json checked (version, macOS signed and notarized, Windows present and signed), release notes from the CHANGELOG.
  9. 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.json beside the page.
  10. 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 with head_commit_id; export main and 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; dispatch deploy-pages.yml for the tag and wait for it; print the store upload steps.
  11. verify: download every public asset and compare it byte for byte; releases/latest names the version; spctl and stapler on 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 in releases.json answers 200, the install scripts equal the release's, the docs carry the tag; on the Windows host the setup's hash and signature.
  12. bump: PR to dev with the next version as X.Y.(Z+1)-dev (--next picks 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 to dev): only the cheap gates. Its runner image has neither npm nor cargo, so scripts/ci-gates.sh runs the allowlist, typos and script tests and prints SKIPPED: 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 green gate/nas therefore does not mean the code builds.
  • **lab/ubu, lab/win**: not set up for gitoodo yet (no lab.yml), so no such status exists.
  • GitHub CI (.github/workflows/ci.yml): every Node and Rust gate on Linux, but only on the exported main and 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
TargetLanePrerequisites
Direct download, macOSfastlane mac directDeveloper 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, Windowsnone: scripts/release-windows.ps1 on WindowsWindows build host, signing command; copy its Gitoodo-<version>-windows-* files, Gitoodo.appinstaller and their .sha256 into target/release/dist/
GitHub release (draft)fastlane github_stagegh 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.ymlthe release tag vX.Y.Z on main of the GitHub repository (see below)
Mac App Storefastlane 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 profilesfastlane mac profiles (create:true)the API key; the App IDs de.gitoodo.app and de.gitoodo.app.service in the developer account
Microsoft Storefastlane 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 direct writes target/release/dist/ (the same as bash scripts/release-mac.sh). The notarization stays in the script (one notarytool submission for app and CLI, one for the DMG); fastlane's notarize action would only duplicate it.
  • github_stage refreshes releases.json, checks the folder with release-check.py dist (every file of releases.json's assets present, sizes and SHA-256 equal, every .sha256 matching, no extra file, URLs on the tag), creates the release vX.Y.Z as 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's set_github_release cannot update a draft or mark the latest release, so the lane uses gh.
  • mac store builds the package; only upload:true uploads it to App Store Connect (deliver, build only: skip_metadata, skip_screenshots), and only submit:true submits it for review. It refuses when src-tauri/tauri.conf.json and the Appfile name different identifiers.
  • windows_store checks that the MSIX carries the release version; upload:true runs msstore publish --noCommit (the package lands in a Partner Center draft submission), submit:true commits it for certification. fastlane has no Microsoft Store support of its own; the third-party sapfire plugin runs on Windows only, Microsoft's msstore CLI also on the Mac. The first submission of the app is made by hand in Partner Center.
  • mac profiles downloads the profiles read-only (sigh); create:true creates 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

  1. checks that the tag is on main, that the Cargo workspace, package.json and tauri.conf.json carry the version and that CHANGELOG.md has its section (release-check.py tree);
  2. waits (up to 60 minutes) until the release vX.Y.Z lists every file named in its releases.json (staged by github_stage or by ship.sh), downloads all of them and runs release-check.py dist; a missing, extra or changed file fails the run and nothing is published;
  3. 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.json names the version and starts deploy-pages for 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.sh

It 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):

  1. Copy the DMG over (scp sets no quarantine flag; add it to act like a browser download: xattr -w com.apple.quarantine "0081;$(printf %x $(date +%s));Safari;" <dmg>).
  2. hdiutil attach, copy Gitoodo.app to /Applications, hdiutil detach.
  3. lipo -archs on Contents/MacOS/* → arm64; spctl -a -vv /Applications/Gitoodo.app → accepted, source=Notarized Developer ID; xcrun stapler validate on the app and the DMG → The validate action worked!.
  4. Open the app once: no Gatekeeper dialog other than the usual "downloaded from the internet" confirmation; the onboarding appears. Quit it.
  5. bash scripts/uninstall.sh --keep-repos (or the published one-liner), then --check reports 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 check

Without 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 distribution passed, lipo -archs = arm64 for gitoodo-app and gitoodo, 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-repos and --check: nothing left.
  • Windows (test machine, Windows 11 x64): the silent setup /S installed per user (publisher "Silvio Lindstedt", Start menu and desktop link), the app started in the desktop session with the onboarding, the CLI reported gitoodo 0.1.0. The service installed from the desktop session ran as Gitoodo\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) when GITOODO_DOCS_VERSION is set (by scripts/release-site.sh) or when the checkout is a tagged v* commit.
  • **dev** for every other build, with a tooltip naming the release it follows (the version in site/releases.json, otherwise package.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.ts with the texts in src/i18n/), the settings structure (src/views/settings/structure.ts) and the pages written for the web in site/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 in site/src/docs/registry.ts), site/docs/dev/ and the usage text of gitoodo --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/CNAME with gitoodo.com (site/src/domain.ts). npm run site:links and npm run site:links:prelaunch fail without it, with another domain in it, or on any link to the former project address on github.io in a text file of the build (the www record below may name the Pages host). scripts/publish-site-prelaunch.sh writes it into the published commit as well: a branch published with gh-pages takes its custom domain from that file, and a force-push without it would drop the domain. A site deployed by the deploy-pages workflow (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.com A 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153 and AAAA 2606:50c0:8000::153, 2606:50c0:8001::153, 2606:50c0:8002::153, 2606:50c0:8003::153; www CNAME silvio-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 (sender gitoodo-web), and the Matomo measurable "Gitoodo Website" must list https://gitoodo.com (scripts/matomo/create-gitoodo-site.php adds it to an existing one); excludeUnknownUrls drops 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=1 does the same as --prelaunch, then npm run site:links:prelaunch). It only runs while site/releases.json says { "release": null }, without VITE_REPO_PUBLIC=1 and without a release tag (site/src/release.ts siteRelease, site/src/docs/version.ts). --production without --prelaunch still fails on { "release": null }.
  • What the page shows: no download buttons, no one-line install and no install.sh / install.ps1 beside the page. The download section says that the first release is on its way (in all six languages, soon in site/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 reads dev with 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 origin https://gitoodo.com; on 2026-11-16 it still answered only the former origin of the Pages address (gitoodo.com got 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 into github.com/silvio-l/gitoodo in any attribute of any page, on any broken internal link or anchor of any page, on installers in site/dist, on a landing page that is not a pre-launch build, and on a missing or wrong CNAME or a link to the former Pages address (Custom domain).
  • Publish (only with the maintainer's approval): the repository stays unpublished, so the deploy-pages workflow (it builds from a tag of the repository) cannot be used. bash scripts/publish-site-prelaunch.sh silvio-l/gitoodo checks site/dist again and prepares one orphan commit with only the built files plus .nojekyll and CNAME (gitoodo.com; anything that looks like source stops it); it is a dry run and pushes nothing. --publish force-pushes that commit to the branch gh-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 at https://gitoodo.com/.
  • Side effect on an empty repository: the first pushed branch becomes the default branch, so github.com/silvio-l/gitoodo would show the built HTML as the repository's code. To avoid that, push a main with only a short README first (that is publishing too and needs the same approval), then gh-pages; or accept it until the release replaces it.
  • **Pre-launch main:** GitHub main holds 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-launch CONTRIBUTING.md and SECURITY.md, .github/FUNDING.yml and the README's images under .github/assets/. No source code, no workflows. It is not kept in this repository; the global pre-push hook 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 main and the export:** repos/gitoodo.json in the export repository sets first_export: "reset". As long as the head of public main carries no GitOrigin-RevId trailer, 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 public main, the first nightly run would instead export internal main on its own as a fresh root commit; the pre-launch main therefore 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" for export-run.sh; never a workflow dispatch). It force-pushes (with lease) one fresh root commit of the exported tree to main: the exported README.md, community files and .github/ (issue and pull request templates, workflows) replace the pre-launch ones, and the pre-launch commit leaves the history of main. 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 the gh-pages branch; a site/releases.json with 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:

  1. Push the tag v<version> of the release commit, merge it into main, and export main and the tag to GitHub silvio-l/gitoodo.
  2. Create the GitHub release v<version> as a draft with the notes from CHANGELOG.md, upload every file of target/release/dist/ (including releases.json, Gitoodo.appinstaller, install.sh, uninstall.sh, install.ps1, uninstall.ps1 and all .sha256), compare the uploaded list with assets in releases.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.
  3. Run the deploy-pages workflow of the GitHub repo for the tag (gh workflow run deploy-pages.yml --ref main -f tag=v<version>): it builds site/dist with scripts/release-site.sh and the release's releases.json and publishes it (https://gitoodo.com/, Custom domain).
  4. Check from a clean machine: the landing page download, curl … | bash on a Mac, irm … | iex on Windows, and the download URLs in releases.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": "…" }]
}
  • downloads holds one entry per platform (mac, windows), the one offered first; a platform without an installer is absent. windows is the MSIX when it is signed (or the only Windows file), otherwise the setup; windowsMsix and windowsSetup list each format that exists. The landing page reads version, releaseUrl and url, size, sha256 of downloads.mac and downloads.windows (site/src/release.ts) and needs both. size is in bytes, sha256 lowercase hex.
  • arch is arm64 (macOS, Apple silicon only) or x64 (Windows).
  • minOs is the macOS version (LSMinimumSystemVersion) or the Windows major version.
  • signed/notarized are checked from the files, not configured; the page may show a hint for an unsigned Windows setup.
  • assets lists every file of the release except the .sha256 files and the manifest.
  • GITOODO_RELEASE_BASE changes the URL base (forks).
  • install.ps1 reads <base>/releases.json (default https://github.com/silvio-l/gitoodo/releases/latest/download, override with -ReleaseUrl or GITOODO_RELEASE_URL) and needs file and sha256 of downloads.windows (or of windowsMsix/windowsSetup for -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 | iex or the older setup .exe from 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 of scripts/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.

Docs version: dev