autosparkle

autosparkle simplifies the process of archiving, exporting, signing, packaging, notarizing, and uploading your new version of the macOS app outside the App Store.

With autosparkle, you no longer have to worry about these steps anymore.

Table of Contents

• Introduction
• Usage
• Features
• Installation
• Environment
• Storage
• Future Enhancements
• Contributing
• License

Introduction

Pushing a new version of your macOS application outside the App Store can be time-consuming. This is because there are several steps required by Apple, in addition to the ones related to Sparkle.

autosparkle is a Ruby command line tool that automates the delivery of your macOS applications outside the App Store. It is implemented around the Sparkle framework.

Note:

This tool is designed for use in a Continuous Delivery (CD) workflow. Although it is possible to run it locally, doing so is not recommended due to the creation of a custom keychain and the mounting of a new DMG. However, if you are comfortable with these steps, you can run it locally without any issues.

Features

• Archive and export your signed application using the provided Developer Application ID certificate.
• Package your app into a signed DMG.
• Customize your DMG appearance by adding a custom background image and a symbolic link to drag the app to the Applications folder.
• Notarize and staple your DMG.
• Automatically sign the Sparkle framework.
• Automatically handle your app versioning based on the specified bump method and the versions uploaded to the storage.
• Generate or update the appcast.xml file used by Sparkle.
• Upload the appcast.xml and your new version to the specified storage.
• Use environment files, making it easy to create a specific one for use in CD (e.g., env.autosparkle.production).

Installation

Using Ruby Gems:

1. Run the following command:

   gem install autosparkle

2. (optional) Add autosparkle to your shell configuration file (e.g. ~/.bashrc or ~/.zshrc) by appending the following line:

   export PATH="<<YOUR_GEMS_DIR>>/autosparkle-x.x.x/bin:$PATH"

   Make sure to replace <<YOUR_GEMS_DIR>>/autosparkle-x.x.x with the actual path to the autosparkle gem on your system.

3. (optional) Run the following command: source ~/.bashrc or source ~/.zshrc.

Manual install:

1. Clone the repository:

   git clone https://github.com/hadiidbouk/autosparkle.git

2. Execute the Ruby script autosparkle.rb, check the Usage section below.

Usage

There are two ways to utilize autosparkle. The first option is to automate the entire process by using the automate command. Alternatively, you can select any of the following commands (export, package, distribute) and build your own solution around them.

All of these commands require you to provide the environment file or its name. If you use the automate command or the export command, which require a project/workspace path, you can simply pass the environment name to the --env option. autosparkle will then search for a file named .env.autosparkle.<<YOUR_ENV_NAME>> in your project directory (where your Xcode project/workspace is located). For example, if you pass --env local, autosparkle will search for .env.autosparkle.local.

It is recommended to use the automate command for several reasons:

1. It automatically handles the app versioning, ensuring consistency between the Info.plist and the appcast.xml.

2. The custom keychain is created once for all the signing steps.

3. All the generated files are conveniently located in one place at ~/Library/Developer/autosparkle/build. When using the commands separately, each command will override any existing files in the build directory.

You can explore the functionality of each command by using the --help flag. For instance:

autosparkle distribute --help

Output:

distribute

  Usage: autosparkle distribute [options]

  Distribute your package to the specified storage and update the appcast.xml file

  Options:
    --dmg-path PATH      Path of the DMG file to be distributed
    --app-display-name NAME Name of the app inside the DMG without the .app extension
    --marketing-version VERSION Marketing version of the app
    --current-project-version VERSION Current project version of the app
    --minimum-macos-version VERSION Minimum macOS version required to run the app, defaults to 14.0

Note:

When using the distribute command, autosparkle will automatically calculate the new marketing version and the current project version from the uploaded appcast file (if it exists). If you want to override these values, make sure to pass them using the --marketing-version and --current-project-version options. Additionally, make sure to set them in your app's Info.plist before exporting the app.

Environment

autosparkle utilizes the dotenv gem to manage environment variables.

The purpose of using environment variable files is to facilitate the transition between the local environment on your personal machine and the production environment on your continuous delivery machine.

Remember to add your local environment file to the .gitignore file and remove any sensitive data from your production environment file. Instead, replace them with the environment variables provided by your continuous delivery system like this:

APP_SEPECIFIC_PASSWORD=$APP_SPECIFIC_PASSWORD

Below are the list of environment variables used by autosparkle:

Note:

Remember to add the SUFeedURL and the SUPublicEDKey to your app's Info.plist. SUFeedURL is the URL of your appcast.xml, which should be publicly accessible online. SUPublicEDKey will be displayed in your terminal after running the bin/generate_keys command.

You can refer to the SparkleTestApp sample project for more information.

Storage

In order to support multiple versions of your macOS application, autosparkle requires access to an online storage for uploading and reading the appcast.xml file and the application versions.

The currently supported storage options are:

• AWS S3

Future Enhancements

Here are some future enhancements planned for autosparkle:

• Support binary delta updates.
• Support for additional storage options.
• Support for the pkg format.
• Distributing autosparkle using Homebrew.

Stay tuned for these exciting updates!

Contributing

Contributions to autosparkle are welcome! If you would like to contribute, please follow these guidelines:

• Fork the repository.
• Create a new branch for your feature or bug fix.
• Make your changes and commit them with descriptive messages.
• Push your changes to your forked repository.
• Submit a pull request to the main repository on the develop branch.

License

autosparkle is licensed under the MIT License.