GitHub Releases are often overlooked or under-utilised within large organisations, where software is not just written for deployment as an application onto a workstation, but also as services consisting of multiple moving parts deployed through multiple environments.
Releases can dramatically improve communication between your team and end users around what’s in each version deployed, and centralise the documentation and artefacts you may need to pass an audit. As such, the approaches described in this article apply equally as well to GitHub.com as they do to GitHub Enterprise users.
GitHub Releases and Git tags
Git allows you to mark specific points in the repository history as important by applying a tag. Tags are commonly used to record a specific version of the software, such as the version of the code that was tested and deployed to your production environment or the version created when new binaries were built from your code for distribution.
GitHub Releases extend on Git tags to provide a dedicated place to publish your release notes and build artefacts alongside your code, as well as announce the new release to people watching your repository.
Releases also offer a few other niceties, such as unique URLs for each release, a static URL for the most recent release, and download counters for each release artefact so you can understand how many times they have been downloaded.
Getting started with Releases
Releases can be created manually through the web UI, or using the Creating a release REST API endpoint. The minimum information required to create a release is the name of an existing tag in the repository, or alternatively, the name for a new tag and the branch or commit SHA you want it to point to.
We recommend choosing a naming convention for your tags which indicates their progression, whether it be as simple as incremental numbers, or the more descriptive Semantic Versioning standard.
Using just this information to create a release, you can navigate to the main page of your repository and select “Releases” to view the results.
With just the minimum information provided, the Releases page shows when the release was created, the tag and commit details, as well as links to compressed archives of the repository code represented by the tag.
Getting more out of Releases
Now that we’ve covered the bare minimum required to create a release, it’s time to look at what the optional fields have to offer.
Describing your release
body text allows you to provide a longer form description, and is often used to detail the release notes. The body supports GitHub Flavoured Markdown so you can provide structure and format to your article. Some users have created tools to fully automate the generation of such release notes, such as the Chronicler project.
A release has two other fields which can be used to communicate to your project team and your users about the status of the release:
Marking a release as a draft will make sure it’s only visible to team members with write access to the repository. This can be useful when you’re not ready for your end users to see the release yet, such as while you are still uploading relevant release artefacts. Once you’re ready for it to be visible, you can edit the release and change it from Draft to Published. New tags are not created while the release is in draft, only when it is published. A draft release can also be discarded, which will delete all information and artefacts assigned to that release.
The pre-release flag lets you communicate that the release is from an unstable branch, or is otherwise not ready for production. This is commonly used for builds during the alpha or beta stages of your software delivery life cycle. While it’s possible to edit a release and disable the pre-release flag after it has been published, this can be confusing for your end users who follow your release timeline. To avoid this confusion, we recommend publishing a new release without the pre-release flag instead.
When creating a release through the web UI, you can attach binary artefacts as part of the creation process. When creating a release in automation using the Creating a release REST API endpoint, you first need to save it as a draft or publish the release before using the Upload a release asset API endpoint to attach your artefacts.
If your project generates many build artefacts – such as binary install files cross compiled for different operating systems – then you can use the APIs to upload them directly from your build servers. Projects like ghr also provide tools to simplify the creation of a release and uploading multiple binary artefacts as a single step.
You can see how many times a file in a Release was downloaded by making a
GET request to the API for a single release, the latest release, or all releases in a repository. Within the JSON payload, every asset has a key called
Bringing it all together
For an example of what a release page looks like with all these aspects in use, check out the Atom project at https://github.com/atom/atom/releases.
Used correctly, GitHub Releases reduce the friction experienced by your project and improve the interactions between the team building the software and the end users.
When users can find detailed release notes alongside the downloadable assets, it enables them to determine if the release contains anticipated features, bug fixes or security patches. Being able to find this information themselves can help to reduce the number of issues raised against your project.
For the project team, it creates a running commentary for each release, stored in a centralised location, allowing for quick answers to questions like, “Which version was that feature released in?”, “What platforms was that release available for?”, and “Can you provide me the same binary which was deployed to Production?”.
- Releases documentation - https://help.github.com/enterprise/user/categories/releases/
- Releases REST API endpoint - https://developer.github.com/enterprise/v3/repos/releases/