Grease

Grease is a utility from Timber.io for creating and maintaining Github releases. It is designed to be used in automated settings, like a CI server.

Installing

Pre-built binaries are available from the repository's releases page. Select the appropriate package for your operating system. The binary is located under the bin folder once you unpack the archive.

Usage

In order to use Grease, you will need a GitHub personal access token. You can create one from your token settings page on your profile. The token should be granted access to the general repo scope.

You can pass your GitHub access token to grease using the --github-token flag after a sub-command or by setting the GITHUB_TOKEN environment variable.

The actual actions you take are performed using one of the sub-commands:

• create-release
• update-release
• upload-assets
• list-files

There are two global flags that can be passed directly after the grease command and before any sub-command:

• --dry-run, -n - will prepare any changes without actually applying them via the GitHub API.
• --debug, -d - turns on verbose output.

The single-letter versions of the flags cannot be combined into a single parameter (like -dn) and must be passed separate (like -d -n).

Creating a Release

You can create a release using the create-release sub-command which takes three positional arguments: the repository name, the tag name, and the commit(ish) the tag should be created from.

grease create-release timberio/grease v1.0.0 566e0e80a473581d05bcdf8a0cddad97ea2fc6c2

In addition to these, you can modify the release information using additional flags. These flags should be listed between create-release and the positional arguments:

• --name - this flag is something that identifies the release to the user. Usually it's the name of the tag, but you might also include a date in the name (like "v0.4.0 - 2017-08-23") or a code-name if you're really cool (like "Sleeping Hyena").
• --notes - Give this flag some text! The notes appear as the body of the release, and it's what users will see. It's a good idea to include information here about what has changed since the last release. You should take care to properly quote the value you pass to notes; if the notes aren't properly quoted, the shell might pass it to Grease as many additional parameters. You can pass the --debug and --dry global flags to make sure that the notes are picked up correctly.
• --draft - this flag shouldn't be followed by a value. If it is present, the release will be set to "Draft" mode to be edited and released later on.
• --pre-release, --pre - this flag shouldn't be followed by a value. If it is present, the release will be marked as a "Pre Release". You'll want to use this if you're releasing betas, nightlies, previews, or anything else that isn't considered part of the stable release set.
• --assets - this flag takes a file glob pattern (like "dist/*") for a value. Grease will try to upload any files matching the glob pattern as assets for your release. If you distribute pre-compiled binaries with your releases, this is the flag you want to use!

The final flag you need to know about is --github-token. A GitHub personal access token is needed to create a release. More details are at the top of the Usage section.

Updating a Release

If you have already created a release (or pushed a git tag), you can update it using Grease with the update-release sub-command which takes two positional arguments: the repository name and the tag name.

grease update-release timberio/grease v1.1.0

This alone won't do much. To take full advantage of the sub-command, you will need to pass additional flags to modify the release. The available flags are the same as those available for create-release (detailed above) and should be specified between update-release and the positional arguments. Please make sure that you provide the GitHub personal access token!

At Timber, we tag releases before pushing them to GitHub. We then use grease update-release to flesh out the release. The resulting script looks something like this:

grease update-release \
  --name $name \
  --notes $notes \
  --assets "dist/*" \
  timberio/grease \
  $tag

You can check out the Makefile's "release" goal for the real deal.

Uploading Assets to a Release

If you have an existing release and only want to add assets to it, you use the upload-assets sub-command which takes three positional arguments: the repository name, the release tag, and a glob pattern used to find files.

grease upload-assets timberio/grease v1.0.0 "dist/*"

The only additional flag this sub-commmand accepts is --github-token which you can also pass in via the GIHUB_TOKEN environment variable. The GitHub personal access token is required in order to upload the assets.

Listing Files Matching Glob Pattern

To check which files will match a glob pattern, you can use the list-files sub-command which takes one positional argument: the glob pattern.

grease list-files "dist/*"

This sub-command does not require a GitHub personal access token to be provided (since it doesn't do anything with GitHub).

It also doesn't accept any additional flags.

Additional Help

You can use the help sub-command to get built-in help from Grease. Just follow the sub-command with the name of another sub-command:

grease help update-release

License & Copyright

Grease is copyright 2017 by Timber Technologies, Inc. and made available under the ISC License. See the LICENSE file in the code repository or included in distribution archives for full details.