macOS App Updates

Your macOS app checks a signed update feed at your own URL. For each release, download the completed build from SessionCloud and copy its DMG, XML and signature to your web server or file-sharing service.

First complete macOS Production Requirements for Developer ID signing and Apple notarization.

1. Choose your update folder

Use an HTTPS folder with permanent direct download URLs. The app must be able to retrieve the files without a login, browser preview page or expiring token. A file-sharing service works only if it serves the actual files under stable URLs with the required filenames; a local or SMB file share is not suitable as the portal update URL.

Enter the folder in App Store → MacOS → MacOS Update Url before building, for example:

https://downloads.example.com/softphone/macos

Do not add a trailing slash or macconfig.xml. The build adds the feed filename. Keep this location available for installed apps: changing the URL in the portal affects future builds and does not change where existing installations check.

Use separate folders for Windows and macOS releases, even if both use the same hosting account.

2. Configure update signing

Set the project’s matching Update Private Key and Update Public Key in App Store. The private key signs the DMG and feed for update verification; the app uses the public key to verify them. Keep the same pair across releases and never put the private key in the public download folder.

The update key pair, Apple Developer ID certificate and App Store Connect API key have different jobs. Update keys verify downloaded releases; the Developer ID certificate establishes the app’s signing identity; the API key authenticates notarization. You need the update keys even when Apple has notarized the DMG.

3. Copy all three release files

Download and extract the completed macOS build ZIP. Copy all three files from that build into your update folder:

For an app named ExamplePhone, publish:

https://downloads.example.com/softphone/macos/ExamplePhone.dmg
https://downloads.example.com/softphone/macos/macconfig.xml
https://downloads.example.com/softphone/macos/macconfig.xml.signature

Publishing only the ZIP is insufficient. Keep the generated filenames and copy the files unchanged. Do not edit the XML, recreate the DMG, re-sign it after the update files were generated, or combine files from different builds. These changes can invalidate update verification.

4. Publish each new version

1. Increase Mac OS Version above the installed release’s version. Changing only the build number does not provide a newer version in the feed.
2. Complete the build, test its DMG and extract the downloaded ZIP.
3. Upload the DMG first, then publish macconfig.xml and macconfig.xml.signature together using staged or atomic publishing if your host supports it.
4. Otherwise, upload all three consecutively in one release window. Clients may temporarily reject an update while hosted files are from different builds.
5. Refresh CDN or hosting caches for all three files.
6. Test the update from an earlier installed version on a separate Mac.

The DMG filename is reused between releases. Keep a private backup of each complete release, and minimise the time between replacing the DMG and publishing its matching feed and signature.

Verify your hosting

Check all three URLs in a private browser window. They must return the actual files without authentication. Check that the enclosure URL in macconfig.xml points to your hosted DMG and that the server allows .signature files.

If no update is offered, check the feed version and the original URL used by the installed app. For signature failures, check cached files, altered XML or DMG contents, mismatched releases and changed update keys. Re-upload the original files together. If the version or URL is wrong, correct the portal settings and rebuild instead of editing signed files.