# 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//.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 = "/" ``` 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 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.