Why we built Bump, an automated pipeline for releasing apps with Sparkle
And how you can use it too…
As part-time authors of Mac software, we’ve felt first-hand the pain of managing our own distribution outside the AppStore. That’s why today we’re introducing Bump, an automated pipeline for releasing apps with Sparkle. Bump has made updating & releasing our apps a much smoother process but before we show you how, a little on how we got here.
For macOS developers today there’s two options for distributing your sparkly new app: distributing “officially” via the AppStore or doing distribution yourself.
For those in the latter camp, Sparkle is the de facto framework. It’s reliable, robust, simple to integrate into an existing app and generally handles all the nuances of software updates.
Sparkle makes integrating the client side straightforward but you’re left to your own devices for the server side of things. A typical release might look something like this:
Write your release notes
This will involve authoring HTML to serve as a readme for users updating your app, and then previewing them to ensure you haven’t missed a tag or messed up your styling
Sign your app
Using Sparkle’s provided scripts, locally sign your app binary (typically a .zip). This is on top of notarising the app itself with Apple so that macOS can trust it
Update a changelog.xml AppCast file
Add your release notes (as HTML), your generated signature from signing your app and a bunch of other metadata to an .xml file
Deploy
Push your updated changelog.xml to a public server somewhere so that users of your app will be prompted to update
This isn’t all that complicated, but it is a lot of steps. And it becomes particularly tedious when you start releasing a lot, or when you forget a specific part of the process because you haven’t released in months. Or, in my case, when you lose your Sparkle private key.
There are many hurdles you can fall at, which makes the process needlessly stressful and error-prone. There are also lot of decisions to make at each step. Where do we host this file? How do we share a private key securely? How do we check and approve each others changes?
In the past, we’ve built various solutions to try and streamline the process for our own apps.
These have included keeping everything in Dropbox to make distribution easy, writing Ruby scripts to turn markdown into HTML for our release notes, and serving files from a GitHub repository to keep track of our changes.
We’ve never created anything we were particularly proud of, or felt we could share with the community, until now.
Introducing Bump
We built Bump to automate this flow for us entirely. Bump makes setting up an entire Sparkle-compatible release pipeline a matter of seconds. Best of all, it makes updates to your app even easier, as simple as writing a single commit.
Let’s take a look at how Bump works. Bump is a GitHub repository template that you can use to generate your own repos, under your own account. It contains a few scripts, and it’s also where you’ll place your app binaries and write your release notes.
Creating your first Bump-powered release
Start using Bump by generating your own Bump-powered repo. We’ll be creating this release entirely in GitHub.
Add your secrets
Bump stores your public files on an AWS S3 bucket that you own. The first thing we need to do then, is add our AWS key and secret to the GitHub repo we just created.
There’s only two required secrets: your AWS_ACCESS_KEY and AWS_SECRET_KEY. If you want Bump to automatically sign your releases with your Sparkle private key, simply add it (you’ll find it in your macOS Keychain) under the key SPARKLE_PRIVATE_KEY.
These secrets never leave GitHub and remain encrypted and private.
Edit the configuration
Open up config.yml and change the default values.
Note that the S3 bucket name must be unique and that your AWS key must have access to manage S3 buckets. We’ll create a new branch with our commit.
Write a release
Edit release/last.md. This file will be used to update your changelog. This file supports markdown which will be automagically turned into HTML for us later. Let’s make our first release a 0.1 release and add some simple notes.
Add your app binary
I’ve made a Hello World macOS app for the purposes of this tutorial. I’ll zip it and add it to my repo making sure the filename matches app_filename in config.yml.
Create a pull request
Now that all our new changes are on a branch, we can create a pull request.
When the pull request is created, Bump’s GitHub Actions springs into… action. You’ll notice we have an automatic commit, that has created our changelog.xml file for us ✨
Merge to production
When the pull request is merged, another GitHub Action spins up which uses Terraform to create an S3 bucket (if it doesn’t already exist), configure permissions for the bucket and add our new files.
This process takes just a few seconds. If we inspect our Action when everything’s complete, we’ll see our production-ready URL in the log output.
curling the URL shows everything is working perfectly. We can add this URL to our Mac app’s info.plist file so it is used to check for updates.
The next time we want to make a release, we follow the same steps. Everything important is within one GitHub repository and we never have to share private keys or secrets around a team just to cut a release.
We’re really excited to never think about app distribution ever again. If you’re interested in using Bump yourself you can check out the guide or skip straight to generating your own Bump-powered repo.
