GitHub Releases with CircleCI

CircleCI is a very powerful Continuious Integration tool, and it already seemlessly integrates with GitHub, however, I've always struggled to understand how to setup the CI to create builds when a tag is created, and add that build to the tag release on GitHub, until now.

To make things simpler in this post, I'm going to assume you've already got methods of creating a build, whether it be Apache Ant for a PHP project, or something else for an iOS application, for example.

This method should work on any project, whether it be a GoLang application, a PHP website, or even a static HTML site.

Demo

We all know you like videos, so, here's one that demos the below process:

 

Setup

In order to use the GitHub API, you'll need to firstly generate a new API key, which can be done via your account settings. Once you've generated the key, you'll need to add it to the CircleCI project environment variables, naming it GITHUB_TOKEN.

Configuration Parts

Here are the parts that build up the CircleCI configuration file, named circle.yml, which is placed within the root of the project:

The first thing that needs to happen here is to install the GoLang application called ghr. This is a very lightweight package that allows the creation of GitHub Releases and the uploading of artefacts:

dependencies:
  pre:
    - go get github.com/tcnksm/ghr

Once that's complete, the package needs to be created using a build service, in this case it's Apache Ant:

compile:
  override:
    - ant package

And then finally the deployment step is listening out for a fixed semver version in order to publish the release to GitHub, for example 1.0.0:

deployment:
  release:
    tag: /(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)/
    commands:
      - ghr -t $GITHUB_TOKEN -u $CIRCLE_PROJECT_USERNAME -r $CIRCLE_PROJECT_REPONAME --replace `git describe --tags` output/

Complete Configuration

Brining that all together makes the complete configuration file:

dependencies:
  pre:
    - go get github.com/tcnksm/ghr

compile:
  override:
    - ant package

deployment:
  release:
    tag: /(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)/
    commands:
      - ghr -t $GITHUB_TOKEN -u $CIRCLE_PROJECT_USERNAME -r $CIRCLE_PROJECT_REPONAME --replace `git describe --tags` output/

Just Send It

Now we've got the project setup, we simply need to create a tag on the project, and push it up to GitHub which should trigger CircleCI to create a build. Once the build is complete it should be uploaded to the GitHub Release.

Feel free to Tweet Me if you have any questions or need any guidance.