Files
lintunes/docs/mac-release.md
T
trav f21c31940f
macOS / Tests (AppleSilicon) (push) Canceled after 0s
macOS / Tests (Intel) (push) Canceled after 0s
macOS / Build (AppleSilicon) (push) Canceled after 0s
macOS / Build (Intel) (push) Canceled after 0s
macOS / Publish the GitHub Release (push) Canceled after 0s
v0.97.0: macOS port (Round 129): OS-aware paths, config and cookies; Mac now-playing, packaging (PyInstaller .app, dmg build, signing notes, CI workflow) and docs
2026-11-17 22:41:48 -08:00

8.9 KiB
Raw Blame History

Releasing the Mac app

Notes for trav. The repo still lives on the Gitea/Forgejo host (origin). GitHub gets a read-only push mirror of it, and GitHub Actions' macOS runners build the two .dmg files and attach them to a GitHub Release. Nothing about the Linux workflow changes: Linux machines keep updating with git pull from origin.

your push ──> origin (Gitea/Forgejo) ──push mirror──> GitHub
                                                   └─ tag vX.Y.Z → .github/workflows/mac.yml
                                                      → Release vX.Y.Z: two .dmg + SHA256SUMS

One-time setup

1. Public or private?

Make the GitHub repo public, for three reasons:

  • Downloads. Mac users download from the Releases page. A private repo's releases are invisible to anyone you haven't invited, and the app's update check asks GitHub's API without logging in, so it can't see them either.
  • Cost. Standard GitHub-hosted runners are free on public repos. On a private repo, GitHub Free includes $12 a month of Actions usage. macOS runners cost $0.062 a minute (Linux is $0.006, so a Mac minute costs about ten Linux minutes). $12 buys about 190 macOS minutes a month. One release runs tests and a build on two Macs, roughly 60–80 minutes in all, so a private repo covers two or three releases a month. (Prices are from GitHub's billing docs, November 2026.)
  • License. The .dmg bundles PyQt6, which is GPL-3.0, so LinTunes as shipped is a GPL combination. Before the first public .dmg, add a LICENSE file (GPL-3.0-or-later fits) to the repo. See packaging/mac/THIRD-PARTY.md.

A private repo still works for trying the pipeline out. Builds then show up as workflow artifacts, which only you can download.

2. Create the GitHub repo

Create an empty repository: no README, no license, no .gitignore. The mirror's first push fills it. Its owner/name is what goes into GITHUB_REPO in step 5.

3. A token for the mirror

On GitHub, go to Settings › Developer settings › Fine-grained personal access tokens › Generate new token:

  • Repository access: only the new repo.
  • Permissions: Contents: Read and write, and Workflows: Read and write. GitHub refuses any push that changes a file under .github/workflows/ from a token without the Workflows permission. Metadata: Read is added for you.
  • Expiration: as long as you're comfortable with. When the token expires, the mirror stops, so put the date in your calendar.

(A classic token works too, with the repo and workflow scopes.)

4. The push mirror on Gitea/Forgejo

In the repo on the Gitea/Forgejo host, open Settings › Repository › Mirror settings and add a push mirror:

  • Git remote repository URL: https://github.com/<owner>/<name>.git
  • Username: your GitHub username. Password: the token.
  • Tick Sync when commits are pushed, and leave a periodic interval as well (say 8h) as a backstop.
  • Click Synchronize now once, and check that the code shows up on GitHub.

Two things to know about push mirrors:

  • The mirror force-pushes and prunes. Anything that exists only on GitHub is deleted on the next sync: commits, branches and tags. Never edit, commit, tag or merge pull requests on GitHub. In particular, never let GitHub create a tag (the "create a new tag on publish" box in the Releases UI, or a workflow that tags). The next sync removes that tag, and the release on it turns back into a draft. This is why tags are made where the code lives (below).
  • If the Gitea/Forgejo host runs Actions of its own, it may pick up .github/workflows/mac.yml too, and those jobs then sit queued forever waiting for a macOS runner. If that happens, turn Actions off for this repo there (Settings › Repository › untick Actions).

5. Name the repo in the app

In lintunes/release_info.py, set:

GITHUB_REPO = "<owner>/<name>"

While this is empty, the Mac app never checks for updates. Commit and release as usual. Every Mac build made after that checks.

Making a release

Releasing is bump, commit, tag, push. The tag is the only new step:

# __version__ in lintunes/__init__.py is already bumped and committed
v="v$(python3 setup.py --version 2>/dev/null | tail -1)"
git tag -a "$v" -m "LinTunes $v"
git push origin master --follow-tags

Run git config push.followTags true once, and a plain git push takes annotated tags along from then on. That keeps the existing habit (each round ends with a commit and a push), and the round's final step only gains the git tag -a.

The mirror carries the tag to GitHub, and the tag starts macOS (.github/workflows/mac.yml). The workflow:

  1. runs the test suite on both kinds of Mac (reported, not blocking, until the Linux-only tests are marked);
  2. builds both apps with packaging/mac/build.sh. It refuses to build if the tag and __version__ disagree;
  3. starts each app against a throwaway library (smoke_test.sh), and checks the disk image mounts and verifies;
  4. creates the GitHub Release vX.Y.Z with LinTunes-X.Y.Z-AppleSilicon.dmg, LinTunes-X.Y.Z-Intel.dmg and SHA256SUMS.

It takes around half an hour. Mac apps that are running see the new release at their next check (a few hours at most) and show the *.

Not every version has to be a Mac release. An untagged version simply never gets a .dmg. To rebuild a release (say, after a failed run), go to Actions › macOS › Run workflow and pick the tag as the ref. The files on the existing release are replaced.

A push to master that touches packaging/mac/ or the workflow builds without publishing, so packaging changes get tested. A plain push to master doesn't build at all, which keeps macOS minutes for releases.

Why not tag automatically when __version__ changes? A workflow on GitHub could do that, but the tag would exist only on GitHub, and the next mirror sync would delete it (see above). Tagging at the source is the only version that survives the mirror.

Turning on Developer ID signing (later)

Unsigned builds make every Mac user go through Open Anyway once. To stop that:

  1. Join the Apple Developer Program ($99 a year).
  2. In Xcode or on developer.apple.com, create a Developer ID Application certificate, and export it with its private key as a .p12 with a password.
  3. Create an app-specific password for your Apple ID at account.apple.com › Sign-In and Security.
  4. On GitHub, add these under Settings › Secrets and variables › Actions:
    Secret Value
    MACOS_CERTIFICATE base64 -i DeveloperID.p12 (the whole output)
    MACOS_CERTIFICATE_PASSWORD the .p12's password
    MACOS_SIGNING_IDENTITY Developer ID Application: Your Name (TEAMID)
    MACOS_NOTARY_APPLE_ID your Apple ID email
    MACOS_NOTARY_TEAM_ID the 10-character team ID
    MACOS_NOTARY_PASSWORD the app-specific password

The next tagged build signs every binary inside out, with the hardened runtime and packaging/mac/entitlements.plist. It then signs the .dmg, notarizes it with notarytool, and staples the ticket. Without the secrets, build.sh says "Developer ID signing skipped" and signs ad hoc, as it does today. Once a signed build is confirmed, take the "Open Anyway" section out of docs/mac.md. Also try removing disable-library-validation from the entitlements.

The signing path has never been run. Expect the first signed build to need fixes.

Building on a Mac by hand

On any Mac with Python 3.11 or later for that Mac's architecture, plus Xcode's command line tools (xcode-select --install):

git clone <origin> lintunes && cd lintunes
PYTHON=python3.13 packaging/mac/build.sh
packaging/mac/smoke_test.sh build/mac/dist/LinTunes.app 20
open build/mac/LinTunes-*.dmg

Everything goes in build/mac/: the venv, the downloaded tools, the app, and the .dmg with its .sha256. A Mac builds only for itself: an Apple Silicon Mac makes the AppleSilicon dmg, and an Intel Mac makes the Intel one.

Updating what's bundled

  • ffmpeg / fpcalc: packaging/mac/tools.json pins each download's URL and SHA-256. To bump one, download the new file, run shasum -a 256 on it yourself, compare the result with the publisher's checksum, then change the URL and hash together. Also update the versions in THIRD-PARTY.md. The ffmpeg builds' publisher stops making Intel release builds from January 2027. Keep the pinned 9.0.2 for Intel until a replacement is chosen.
  • PyInstaller: pinned at the top of build.sh.
  • Python: PYTHON_VERSION in the workflow.
  • Minimum macOS: MINIMUM_MACOS in packaging/mac/plist.py. It follows PyQt6's macOS wheel tag (14.0 for PyQt6 6.12).
  • The icon: python3 scripts/make_icons.py --only mac rewrites packaging/mac/LinTunes.icns from packaging/lint.jpg. Commit the result.