Deploying Your Assets To GitHub Releases

Wercker is a Docker-Native CI/CD Automation platform for Kubernetes & Microservice Deployments

Benno van den berg
Benno van den berg
May 9, 2014

At Wercker we view deployment as a broad topic. Traditionally, we think about servers and Platform-as-a-Service providers when talking about deployment, but delivering static assets or uploading artifacts is of course deployment as well!

Today, we dive into how to upload your artifacts to the GitHub releases API.

The GitHub releases API

GitHub releases was announced in this blogpost, where you can read up on it.

In short, GitHub releases is a way to mark certain git commits as releases and add changelogs to them. It even allows you to distribute binaries or packaged versions of your code with a release.

How do I use it?

We’ve created two Wercker steps that you can incorporate in your pipeline to release your code to GitHub. The first is wercker/github-create-release, which will create a release on GitHub. The second one is wercker/github-upload-asset, which allows you to upload a file and associate it with a GitHub release.

Creating a GitHub token

For both steps you will need a GitHub token coupled to an account which has enough permissions to be able to create releases. First goto Account settings, then gotoApplications for the user. Here you can create a token in thePersonal access tokens section. For a private repository you will need the reposcope and for a public repository you will need the public_repo scope. Then it is recommended to save this token on wercker as a protected environment variable.

Wercker/github-create-release

The wercker/github-create-release step will create a release on GitHub. It will require a GitHub token and a tag. Check out thewercker/github-create-release step here

The tag can be anything you like, but it needs to be unique for this repository. That said, it is recommended that you use Semantic Versioning for a tag, like 1.0.0 or2.5.1. See semver.org for more information about Semantic Versioning.

If you create a release without a title, then GitHub will use the tag and the commit message of the commit. To change this set the title parameter. Another usefull parameter is draft, this will not make the release public yet. This way you’ll be able to do a final check on the GitHub page and then publish it.

Let’s take a look at a small example:

deploy:
    steps:
        - github-create-release:
            token: $GITHUB_TOKEN
            tag: v1.0.0

This will create a GitHub release with the tag v1.0.0. Since most of the parameters are left empty, wercker and GitHub will provide defaults where applicable. See theREADME for the default strategies of the various parameters.

In the previous example we’ve hadcoded the version, but most application have their own way to keeping track of the version. In most cases you want to get that version, export it as a environment variable and then pass it as a parameter to the step:

deploy:
    steps:
        - script:
            name: get version from rake
            code: export APP_VERSION=$(rake appversion)
        - github-create-release:
            token: $GITHUB_TOKEN
            tag: $APP_VERSION

In this fictional example we capture the output from rake appversion, store it in the $APP_VERSION environment variable and then use is as a parameter. This is example however requires a rake task called appversion to be created.

deploy:
    steps:
        - github-create-release:
            token: $GITHUB_TOKEN
            tag: $GITHUB_RELEASE_VERSION
            title: Util library $GITHUB_RELEASE_VERSION
            draft: true

This last example will get the tag from the $GITHUB_RELEASE_VERSIONenvironment variable. This is set as a wercker environment variable.

image

wercker/github-upload-asset

The wercker/github-upload-asset step uploads an asset and add it to a specific GitHub release. This step requires a GitHub token, release_id and a file. Thefile should point to a regular file, this will most likely be a artifact of your build process. Check out the wercker/github-create-release step here

This step also has a lot of parameters with defaults, so be sure to check the READMEfor the default strategies.

Let’s look at a simple example:

deploy:
    steps:
        - github-upload-asset:
            token: $GITHUB_TOKEN
            file: build.tgz
            release_id: 1

This will upload the file build.tgz to a release with the id 1. The filename will be retrieved from basename and file will be used to figure out the content-type. You could however overwrite these with parameters.

If you are using the wercker/github-upload-asset step after thewercker/github-create-release step, then you won’t need to specify therelease_id. The wercker/github-create-release exposes the release id as a environment variable and wercker/github-upload-asset will use that one.

deploy:
    steps:
        - github-create-release:
            token: $GITHUB_TOKEN
            tag: v1.0.0
        - github-upload-asset:
            token: $GITHUB_TOKEN
            file: build.tgz

Complete example

The wercker.yml is the way to define your build and deployment pipeline on wercker. Below is a complete working example of a deployment pipeline to the GitHub releases API that leverages the abovementioned steps.

build:
    steps:
        - script:
            name: test application
            code: make test
        - script:
            name: create distribution
            code: make dist
        - script:
            name: create documentation
            code: make docdist
deploy:
    steps:
        - github-create-release:
            token: $GITHUB_TOKEN
            tag: $GITHUB_RELEASE_VERSION
            title: Application $GITHUB_RELEASE_VERSION
            draft: true
        - github-upload-asset:
            token: $GITHUB_TOKEN
            file: build.tgz
            filename: app-$GITHUB_RELEASE_VERSION.tgz
        - github-upload-asset:
            token: $GITHUB_TOKEN
            file: documentation.tgz
            filename: app-documentation-$GITHUB_RELEASE_VERSION.tgz

The build process will first run some tests and then creates two artifacts build.tgzand documentation.tgz. The wercker application has two wercker environment variables, $GITHUB_TOKEN and $GITHUB_RELEASE_VERSION. It will use$GITHUB_RELEASE_VERSION as the tag, but will change the title to have Applicationin front of the version. Then it will add the two artifacts to the release, but with the filename changed to include the version:

Things to come

Currently no JSON encoding will be done, so you need to make sure you do your own JSON encoding. This is something which will come to a future version. If you’re going to do your own encoding then make sure you lock the version of the step. Otherwise double encoding will happen when the JSON encoding is introduced.

Another thing the step is lacking at is error handling. If you get a error from curl in the logs, then checkout the appropriate README’s.

There will be a few version providers coming for a few of the most popular package management systems, like npm!

Earn some stickers!

Let us know about the applications you build with wercker. Don’t forget to tweet out a screenshot of your first green build with #wercker and we’ll send you some@wercker stickers.

Follow us on twitter as well to stay in the loop.

 

 

Topics: Product, Containers, Tutorials