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 goto
Applications for the user. Here you can create a token in the
Personal 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 step will create a release on GitHub. It will require a GitHub token and a
tag. Check out the
wercker/github-create-release step here
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
2.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 the
README 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.
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 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
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 the
wercker/github-create-release step, then you won’t need to specify 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
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
documentation.tgz. The wercker application has two wercker environment variables,
$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.