Painless Shipping with GitHub Releases

Hafenschlepper 01 KMJ

All software developers who create a product need to think about how to deliver that product to their end users. We’re fortunate to live in a time when the internet has made releasing software much simpler. Not only that, but modern source control makes managing multiple releases relatively easy.

In 2013, GitHub announced Releases–an easy way to ship software to end users. In this post, I’ll touch on a few aspects of GitHub Releases that make it a compelling choice for software delivery.

Tagging and SemVer

Releases are created in GitHub whenever a tagged commit is pushed. GitHub recommends using semantic versioning (SemVer) for your tags. Within the SemVer scheme, versions consist of three numbers: MAJOR.MINOR.PATCH. SemVer summarizes incrementing version numbers as follows:

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backwards-compatible manner
  3. PATCH version when you make backwards-compatible bug fixes

As an example, when you’re ready to release the first version of your software, you may want to tag it with 1.0.0. After the release, a user may report a minor bug which you promptly fix. At that point, you can tag the fix with 1.0.1. Subsequent releases are tagged accordingly.

GitHub Releases

A new Release is created in GitHub whenever a tagged commit is pushed to your repository. You can view a repository’s releases by navigating to the repository on GitHub and clicking Releases. Here is a simple example of two releases that were created on one of my test project repositories:

Two releases in a GitHub Repository

In the above case, I have released two versions of the software. There are two ways to create releases in GitHub: by tagging a commit manually or by using the Draft a new release option on the website.

For version 1.0, I used the Draft a new release option, which allows an author to create a release on the GitHub webpage. With this approach, you can directly edit release notes using markup. GitHub also formats things nicely and automatically includes downloads of the source code. It’s also possible to upload binary files with the release. If you want to release software without open-sourcing it, simply upload the binary of your library or application as part of the new release.

For the second version, I tagged a commit test-commit-tag-release-2.0 “manually” to demonstrate that GitHub will still create a release, even without SemVer. However, it won’t be marked as the Latest release on the page.

Convenient Hosting and Deployment

Recently, I have been working with a client that regularly releases an iOS SDK to their clients. As part of that work, I helped them make their software available to developers using CocoaPods. Creating a new CocoaPod requires you to write a podspec file. Most CocoaPods are open-source, but they also support closed-source binary releases.

The podspec file requires a source URL that links to the code or binary–so a developer needs to host the software somewhere. GitHub makes this easy by providing permanent links for all releases!

GitHub release links

The links will have a format like This URL can be used with any version control system you link (super-convenient if you’re already using GitHub to host your repository anyway).

I wasn’t aware of GitHub Releases until I had to start deploying the SDK described above, so I’m still new to them. I’d love to hear how you’ve used them for your own software projects.