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
210 lines
8.9 KiB
Markdown
210 lines
8.9 KiB
Markdown
# 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:
|
||
|
||
```python
|
||
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:
|
||
|
||
```sh
|
||
# __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`):
|
||
|
||
```sh
|
||
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.
|