ghr

Upload multiple artifacts to GitHub Release in parallel

1,234

View on GitHub

Top Related Projects

go-github

10,287

Go library for accessing the GitHub v3 API

Quick Overview

ghr is a command-line tool that allows you to upload your GitHub repository releases as well as individual files to GitHub. It provides a simple and efficient way to manage your project's releases and distribution.

Pros

Automated Release Management: ghr simplifies the process of creating and managing GitHub releases, making it easier to distribute your project's artifacts.
Supports Multiple File Types: The tool can handle various file types, including binaries, source code, and other assets, making it versatile for different project needs.
Concurrent Uploads: ghr supports concurrent uploads, which can significantly speed up the release process, especially for large projects.
Flexible Configuration: The tool offers various configuration options, allowing you to customize the release process to fit your specific requirements.

Cons

Dependency on GitHub API: ghr relies on the GitHub API, which means that any changes or limitations in the API could potentially affect the tool's functionality.
Limited Functionality: While ghr is focused on release management, it may not provide the full range of features that some users might expect from a more comprehensive release management solution.
Potential Authentication Issues: Users may encounter authentication-related issues, especially if they have complex GitHub access control configurations.
Lack of Graphical User Interface (GUI): ghr is a command-line tool, which may not be preferred by users who prefer a more visual interface for managing releases.

Getting Started

To get started with ghr, follow these steps:

Install the ghr tool:
```
go get -u github.com/tcnksm/ghr
```
Authenticate with GitHub:
```
export GITHUB_TOKEN=<your_github_token>
```
Replace <your_github_token> with your personal GitHub access token.
Create a new release:
```
ghr -t ${GITHUB_TOKEN} -u ${GITHUB_USER} -r ${GITHUB_REPO} -c ${COMMIT_SHA} ${TAG_NAME} ${PATH_TO_RELEASE_ASSETS}
```
Replace the following placeholders:
- ${GITHUB_USER}: Your GitHub username
- ${GITHUB_REPO}: The name of your GitHub repository
- ${COMMIT_SHA}: The commit SHA of the release
- ${TAG_NAME}: The tag name for the release
- ${PATH_TO_RELEASE_ASSETS}: The path to the release assets you want to upload
Verify the release on your GitHub repository's "Releases" page.

That's it! You've successfully created a new release using ghr. Refer to the project's documentation for more advanced usage and configuration options.

Competitor Comparisons

go-github

10,287

Go library for accessing the GitHub v3 API

Pros of go-github

Comprehensive coverage of the GitHub API, with support for a wide range of endpoints and features.
Well-documented and actively maintained, with a large community of contributors.
Provides a structured and type-safe interface for interacting with the GitHub API.

Cons of go-github

Relatively complex and may have a steeper learning curve compared to simpler tools like ghr.
May be overkill for simple use cases that only require a subset of the GitHub API functionality.
Requires more boilerplate code to perform common tasks compared to more specialized tools.

Code Comparison

go-github:

client := github.NewClient(nil)
user, _, err := client.Users.Get(context.Background(), "octocat")
if err != nil {
    fmt.Printf("Error: %v", err)
    return
}
fmt.Println(user.GetLogin())

ghr:

ghr.NewGithubRelease("v1.0.0", "path/to/artifact.zip")

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

ghr

ghr creates GitHub Release and uploads artifacts in parallel.

Demo

This demo creates GitHub Release page with v1.0.0 tag and uploads cross-compiled golang binaries.

You can see release page here.

Usage

Using ghr is simple. After setting GitHub API token (see more on GitHub API Token section), change into your repository root directory and run the following command:

$ ghr [option] TAG [PATH]

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

ghr assumes that you are in a git repository when executed. This is because normally the artifacts you want to upload to a GitHub Release page are in that repository or generated there. With this assumption, ghr implicitly reads repository URL from .git/config file. But you can change this kind of information, see Options section.

GitHub API Token

To use ghr, you need to get a GitHub token with an account which has enough permissions to create releases. To get a token, visit GitHub 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 need repo scope and for a public repository you need public_repo scope.

When using ghr, you can set it via GITHUB_TOKEN env var, -token command line option or github.token property in .gitconfig file.

For instance, to set it via environment variable:

$ export GITHUB_TOKEN="....."

Or set it in github.token in gitconfig:

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

Note that environment variable take precedence over gitconfig value.

GitHub Enterprise

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

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

Example

To upload all files 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

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
    -n TITLE \        # Set release title
    -b BODY \         # Set text describing the contents of the release
    -p NUM \          # Set amount of parallelism (Default is number of CPU)
    -delete \         # Delete release and its git tag in advance if it exists (same as -recreate)
    -replace \        # Replace artifacts if it is already uploaded
    -draft \          # Release as draft (Unpublish)
    -soft \           # Stop uploading if the same tag already exists
    -prerelease \     # Create prerelease
    -generatenotes \  # Generate Release Notes automatically (See below)
    TAG PATH

Install

If you are a macOS user, you can use Homebrew:

$ brew install ghr

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

Or you can use go install.

$ go install github.com/tcnksm/ghr@latest

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.

Generate Release Notes

GitHub added the ability to automatically generate the body of a Release based on a format specified in .github/release.yml in Oct 2021. You can read more about that format here. ghr now has the -generatenotes flag to enable that content to be programmatically added instead of manually supplying the body.

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 using correct variables e.g. GITHUB_TOKEN=$GITHUB_TOKEN TEST_REPO_OWNER=tcnksm TEST_REPO_NAME=ghr make test
Run gofmt -s -w .
Create new Pull Request

Author

Taichi Nakashima

Top Related Projects

go-github

10,287

Go library for accessing the GitHub v3 API

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot