8.9 KiB
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
LICENSEfile (GPL-3.0-or-later fits) to the repo. Seepackaging/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.ymltoo, 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:
- runs the test suite on both kinds of Mac (reported, not blocking, until the Linux-only tests are marked);
- builds both apps with
packaging/mac/build.sh. It refuses to build if the tag and__version__disagree; - starts each app against a throwaway library (
smoke_test.sh), and checks the disk image mounts and verifies; - creates the GitHub Release
vX.Y.ZwithLinTunes-X.Y.Z-AppleSilicon.dmg,LinTunes-X.Y.Z-Intel.dmgandSHA256SUMS.
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:
- Join the Apple Developer Program ($99 a year).
- In Xcode or on developer.apple.com, create a Developer ID
Application certificate, and export it with its private key as a
.p12with a password. - Create an app-specific password for your Apple ID at account.apple.com › Sign-In and Security.
- On GitHub, add these under Settings › Secrets and variables › Actions:
Secret Value MACOS_CERTIFICATEbase64 -i DeveloperID.p12(the whole output)MACOS_CERTIFICATE_PASSWORDthe .p12's password MACOS_SIGNING_IDENTITYDeveloper ID Application: Your Name (TEAMID)MACOS_NOTARY_APPLE_IDyour Apple ID email MACOS_NOTARY_TEAM_IDthe 10-character team ID MACOS_NOTARY_PASSWORDthe 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.jsonpins each download's URL and SHA-256. To bump one, download the new file, runshasum -a 256on it yourself, compare the result with the publisher's checksum, then change the URL and hash together. Also update the versions inTHIRD-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_VERSIONin the workflow. - Minimum macOS:
MINIMUM_MACOSinpackaging/mac/plist.py. It follows PyQt6's macOS wheel tag (14.0 for PyQt6 6.12). - The icon:
python3 scripts/make_icons.py --only macrewritespackaging/mac/LinTunes.icnsfrompackaging/lint.jpg. Commit the result.