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.
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
once you unpack the archive.
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
You can pass your GitHub access token to grease using the
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:
There are two global flags that can be passed directly after the
command and before any sub-command:
-n- will prepare any changes without actually applying them via the GitHub API.
-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
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
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
--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
--dryglobal 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- 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
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
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
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
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
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.
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.