ghr

ghr is a simple tool to create GitHub Release and upload artifacts by only one command. ghr uploads multiple artifacts in parallel.

Demo

This demo shows simple usage of ghr. It creates GitHub Release page for version v1.0.0 and uploads cross-compiled golang binaries there.

You can see release page here.

Usage

To use ghr is really simple. After setting GitHub API token (see more on GitHub API Token section), change directory to GitHub repository root and run the following command,

$ ghr [option] TAG PATH

You must provide TAG (git tag to use this release) and PATH to artifacts you want to upload. You can specify a file or a directory. If you provide a directory, all file in that directory will be uploaded.

ghr assumes that you are in the GitHub repository root when executed. This is because normally the artifacts you want to upload to a GitHub Release page is related to that repository or generated by codes on that repository. With this assumption, ghr implicitly reads information like repository URL or owner name from .git/config file. But You can change this kind of information via option, see Options section.

GitHub API Token

To be able to use ghr, you will first need to create a GitHub token with an account which has enough permissions to be able to create releases. First, go to Account settings page, then go to Applications for the user. Here you can create a token in the Personal access tokens section. For a private repository you will need the repo scope and for a public repository you will need the public_repo scope.

Then you need set it via environmental var GITHUB_TOKEN, -token command line option or github.token property in .gitconfig file.

For instance, to set it via environmental variable:

$ export GITHUB_TOKEN="....."

Or set it in github.token in gitconfig:

$ git config -global github.token "....."

Note that environmental variable takes priority over gitconfig value.

GitHub Enterprise

You can use ghr for GitHub Enterprise. Change API endpoint via the enviromental variable.

$ export GITHUB_API=http://github.company.com/api/v3

Example

To upload all package in pkg directory with tag v0.1.0

$ ghr v0.1.0 pkg/
--> Uploading: pkg/0.1.0_SHASUMS
--> Uploading: pkg/ghr_0.1.0_darwin_386.zip
--> Uploading: pkg/ghr_0.1.0_darwin_amd64.zip
--> Uploading: pkg/ghr_0.1.0_linux_386.zip
--> Uploading: pkg/ghr_0.1.0_linux_amd64.zip
--> Uploading: pkg/ghr_0.1.0_windows_386.zip
--> Uploading: pkg/ghr_0.1.0_windows_amd64.zip

Or if you want to replace artifact which is already uploaded:

$ ghr -replace v0.1.0 pkg/

Options

You can set some options:

$ ghr \
    -t TOKEN \        # Set Github API Token
    -u USERNAME \     # Set Github username
    -r REPO \         # Set repository name
    -c COMMIT \       # Set target commitish, branch or commit SHA
    -p NUM \          # Set amount of parallelism (Default is number of CPU)
    -replace \        # Replace asset if target is already exists
    -delete \         # Delete release and its git tag in advance if it exists
    -draft \          # Release as draft (Unpublish)
    -prerelease \     # Crate prerelease
    TAG PATH

Install

If you are OSX user, you can use Homebrew:

$ brew tap tcnksm/ghr
$ brew install ghr

If you are in another platform, you can download binary from release page and place it in $PATH directory.

Integration with CI-as-a-Service

You can integrate ghr with CI-as-a-Service to release your artifacts after test passed. It's very easy to provide latest build to your user continuously.

See Integrate ghr with CI as a Service page.

VS.

aktau/github-release - github-release can also create and edit releases and upload artifacts. It has many options. ghr is a simple alternative. And ghr will parallelize upload artifacts.

Contribution

Fork (https://github.com/tcnksm/ghr/fork)
Create a feature branch
Commit your changes
Rebase your local changes against the master branch
Run test suite with the make test command and confirm that it passes
Run gofmt -s
Create new Pull Request

You can get source with go get:

$ go get -d github.com/tcnksm/ghr
$ cd $GOPATH/src/github.com/tcnksm/ghr
$ make install

ghr uses vendoring feature for some third party packages. If you use go1.5, then set GO15VENDOREXPERIMENT=1.

Author

Taichi Nakashima

delgiudices/ghr

ghr