Getting started · HarborPilot

Getting started: ship a new Mac app with HarborPilot

This guide walks through HarborPilot with an app that has never shipped outside Xcode: no Sparkle, no update key, no feed. The screenshots follow Tidemark, a sample tide app, from HarborPilot's first launch to Tidemark 1.0 being live on its own host.

By Francisco Cantu ·

Before you start

  • A Mac with macOS 26 or later and Xcode 26 or later.
  • An Apple Developer Program membership, with a Developer ID Application certificate in your Keychain, or Xcode signed in to an account that can use a cloud-managed Developer ID certificate.
  • An App Store Connect API key for notarization: the .p8 file, its Key ID, and your Issuer ID. Step 2 shows where to get one.
  • An Xcode project (.xcodeproj or .xcworkspace) that builds your Mac app. It doesn't need Sparkle yet.
  • A place to host files at an HTTPS address on a domain you own: Cloudflare R2, an FTP server, or any web server you can upload to.

Commit your work before you start. HarborPilot's edits are easiest to review against a clean working tree, and it never commits for you.

1. Check your Mac on first launch

The first time you open HarborPilot, a short welcome tour introduces it. Then the main window checks three things and shows them under the drop area: Xcode, your signing certificate, and Apple notarization. A green check means that part is ready.

HarborPilot's first window: a drop area for an Xcode project, with checks for Xcode 27.2, Signing certificate found, and Apple notarization not set up
Xcode and the signing certificate check out. Notarization still needs a key.

If the certificate check says Xcode will sign for you, HarborPilot exports with Xcode's automatic signing, using the account signed in to Xcode.

2. Add your notarization key

Click Set Up next to Apple notarization. In App Store Connect, open Users and Access → Integrations → App Store Connect API, create a key with the Developer role, and download it. Apple lets you download the .p8 file only once, so keep it somewhere safe.

Drop the file on the sheet, enter the Key ID and Issuer ID, and click Add Key. HarborPilot stores the key in your Keychain as a notarytool profile. You add it once, and every app you connect uses it.

The Set up Apple notarization sheet, with a drop area for the AuthKey .p8 file and fields for Key ID and Issuer ID
One key covers every app you release.

3. Connect your app

Drop your Xcode project on the window, or click Choose Project…. HarborPilot reads the project without building or changing it. Tidemark has no Sparkle yet, so HarborPilot lists what it will set up: the Sparkle package, a key that signs your updates, and your update address.

Then it asks one question: Where will you upload updates? Type the folder on your host where the update files will live, such as https://updates.fracturedbits.com/tidemark/. Below it, HarborPilot shows the feed address it will build into your app.

Tidemark is almost ready: HarborPilot will set up Sparkle updates, a key that signs your updates, and your update address, with the upload folder https://updates.fracturedbits.com/tidemark/
One question: where your update files will live.

Choose this address carefully. Every copy of your app checks it for as long as it's installed, so use a domain you own rather than a temporary host.

Hosting on Cloudflare? Click Set Up on Cloudflare…, choose an address on a domain in your Cloudflare account, and sign in. HarborPilot creates the bucket, serves it at your address, and keeps an upload key in your Keychain, so each release can upload itself. Click Use This Address to fill in the folder. A brand-new address can take a while to answer while its certificate is issued; HarborPilot checks again after your first release.

Set Up Hosting on Cloudflare: choose your address, sign in to Cloudflare, and use it
Set Up on Cloudflare ends with Tidemark uploading each release by itself.

To upload by FTP instead, connect with your folder's web address, then add your server in App Settings → Upload. For other hosts, you'll drag three files after each release.

4. Review the changes, then set up

Click Review the 4 changes (the number depends on your project) to see every edit as a diff before anything is written, such as adding the Sparkle package to the project and creating an Info.plist with your update address. HarborPilot backs up each file first, and Undo restores the backup.

4 changes to your project: diffs for adding the Sparkle package to project.pbxproj and creating Configuration/Tidemark-Info.plist
Every edit is a small diff you can read before it happens.

When you're ready, click Set Up Tidemark (your app's name appears on the button).

5. Back up the key and add Check for Updates

Sparkle is now in the project and the update address is set. Two things need you:

  • Save a backup of your update key. Click Save Backup… and keep the file in your password manager. If the key is lost, people who already have your app can't get another update.
  • Add "Check for Updates…" to your menu. HarborPilot adds CheckForUpdates.swift to the project and shows two lines to paste into your App file: one above var body, and one after your WindowGroup. Open TidemarkApp.swift in Xcode takes you straight there. In an AppKit app, the two lines go in your app delegate instead: one inside the class, and updater.installMenuItem() at the end of applicationDidFinishLaunching(_:).
Two quick things and Tidemark is ready: save a backup of your update key, and add Check for Updates to your menu by pasting two lines
The two steps only you can do.

Then click Check My Setup. HarborPilot builds the app once, without notarizing, and confirms that Sparkle is inside the app, the update address is set, the update key matches the one in your Keychain, and the hardened runtime is on.

Tidemark is ready to release: update key backed up, Check for Updates is in the app, and Sparkle, the update address, the update key, and the hardened runtime all check out
Everything a first release depends on, checked before Apple sees it.

If you skip pasting the two lines, your first release stops and offers Add Check for Updates…, because people who install a release that never starts Sparkle might never get another update.

6. Start the trial and build 1.0

Back in the main window, your app is Ready for its first release. Click Build & Release 1.0.

Tidemark's home screen: Ready for its first release, with a Build & Release 1.0 button and no releases yet
Signing, notarization, and Sparkle are checked before the button appears.

The first time, HarborPilot asks you to start the 14-day trial or enter a license key. The trial includes every feature, on this Mac, with no account or payment.

Start your free trial: Start 14-Day Trial, or paste a license key from your purchase email
Start the trial when you're ready to release, not before.

Write what's new, in plain text or Markdown, and click See how it looks to your users to preview it. HarborPilot suggests your project's version (1.0 if it has none) with build 1; click Change to use a different one. The sheet also shows the branch you're releasing from and warns about uncommitted changes, such as Set Up's edits. Commit them first if you want the release to match a commit.

Build & Release Tidemark 1.0: release notes in Markdown, version 1.0, build 1, ZIP
Notes, a version, and one button.

Click Build & Release.

7. Let Apple check it

HarborPilot archives the app, exports it with your Developer ID, checks the exported app, and sends it to Apple. Most of the wait is Apple's check. You can close the window, and you'll get a notification when it's done. If you quit HarborPilot, the release picks up where it left off, with the same Apple submission.

Apple is checking Tidemark 1.0: Build is done, Notarize with Apple is in progress, Sign and package is next
You don't need to watch this part.

When Apple accepts the app, HarborPilot staples the ticket, signs the update for Sparkle, and writes the feed.

Tidemark 1.0 is ready to upload: notarized and signed, with an Upload Files button
Notarized, stapled, and signed for Sparkle.

If Apple rejects the app, the notarization errors guide explains how to read Apple's log.

8. Upload three files and check it's live

If you set up Cloudflare or FTP, there's nothing to drag: HarborPilot uploads the files for you and checks they're live. Otherwise, click Upload Files. HarborPilot lists three files, in the order they go up:

  • Tidemark-1.0.zip, the update itself.
  • Tidemark-latest.zip, a copy for your website's download link.
  • appcast.xml, the feed, last, so nobody is pointed at a file that isn't there yet.

Drag them to your upload folder, then click I've Uploaded Them. Check. HarborPilot downloads the feed and files from your address and confirms they're the ones it built.

Put Tidemark 1.0 on your host: upload the app, then the feed, then the check shows Tidemark 1.0 is live
Live means people get the update the next time the app checks.

After your first release

  • Link your website's download button to the latest file in your upload folder, such as https://updates.fracturedbits.com/tidemark/Tidemark-latest.zip. Each release replaces it, so the link always gets the newest version.
  • Test a real update. Install 1.0 from that link, release 1.0.1, and choose Check for Updates… in the installed copy.
  • The basics are now pinned. HarborPilot checks every later release against the feed address, bundle identifier, and update key from this one, because copies already installed depend on them.

From here, every release is the same: write the notes, click Build & Release, and upload. To understand what Set Up did under the hood, read how to set up Sparkle in a modern Mac app and hosting your Sparkle appcast on Cloudflare R2.

Simplify your next release with HarborPilot.

Tidemark went from an Xcode project to a live 1.0 with one setup pass and one button. Connect your own app, answer one question, and ship your first release the same way.

Sources and further reading

Service limits and Apple requirements can change. Check the linked documentation before publishing. HarborPilot is not affiliated with Apple, Cloudflare, or the Sparkle project.