gh-publish

Create a release for a node package on GitHub.

Features

• Uses the Github Releases API to create a new github release.
• Defaults to using information from package.json and a keepachangelog.com-style CHANGELOG.md.

Install

$ npm install gh-publish

Usage

Command-line interface

$ gh-publish
Your GitHub username: ungoldman
Your GitHub password: ✔✔✔✔✔✔✔✔

creating release v1.0.0 for ungoldman/cool-project

name:               v1.0.0
tag_name:           v1.0.0
target_commitish:   9561804a4d1fca2525d3207bec4907dd5ec7a705
body:

* engage

? publish release to github? Yes
https://github.com/ungoldman/cool-project/releases/tag/v1.0.0

Should be run at the root of the project to be released.

Expects a package.json and CHANGELOG.md in the working directory.

Prints release URL to stdout on success.

Uses ghauth for authentication with Github. A Github API OAuth token is saved to the gh-publish config directory after the first time authenticating. Note that the config directory is determined by application-config and is OS-specific.

Get usage info by running with --help or -h.

$ gh-publish --help
Usage: gh-publish [options]

Examples:
  gh-publish -n v2.0.3 -c master -d    create a draft release with title v2.0.3 tagged at HEAD of master


Options:
  -t, --tag_name          tag for this release
  -c, --target_commitish  commitish value for tag
  -n, --name              text of release title
  -b, --body              text of release body
  -o, --owner             repo owner
  -r, --repo              repo name
  -d, --draft             publish as draft                          [default: false]
  -p, --prerelease        publish as prerelease                     [default: false]
  --dry-run               dry run (stops before release step)       [default: false]
  -w, --workpath          path to working directory                 [default: "<current working directory>"]
  -e, --endpoint          GitHub API endpoint URL                   [default: "https://api.github.com"]
  -a, --assets            comma-delimited list of assets to upload  [default: false]
  -h, --help              Show help
  -v, --version           Show version number

Node API

var ghRelease = require('gh-publish')

// all options have defaults and can be omitted
var options = {
  tag_name: 'v1.0.0',
  target_commitish: 'master',
  name: 'v1.0.0',
  body: '* init\n',
  draft: false,
  prerelease: false,
  repo: 'gh-publish',
  owner: 'roman0x58',
  endpoint: 'https://api.github.com' // for GitHub enterprise, use http(s)://hostname/api/v3
}

// options can also be just an empty object
var options = {}

// auth is required
// it can either be a username & password...
options.auth = {
  username: 'roman0x58',
  password: 'XXXXXXXX'
}

// or an API token
options.auth = {
  token: 'XXXXXXXX'
}

ghRelease(options, function (err, result) {
  if (err) throw err
  console.log(result) // create release response: https://developer.github.com/v3/repos/releases/#response-4
})

Defaults

All default values taken from package.json unless specified otherwise.

| name | description | default | | ---: | ----------- | ------- | | tag_name | release tag | 'v' + version | | target_commitish | commitish value to tag | HEAD of current branch | | name | release title | 'v' + version | | body | release text | CHANGELOG.md section matching version | | owner | repo owner | repo owner in repository | | repo | repo name | repo name in repository | | draft | publish as draft | false | | prerelease | publish as prerelease | false | | assets | release assets to upload | false | | endpoint | GitHub API endpoint URL | https://api.github.com |

Override defaults with flags (CLI) or the options object (node).

Standards

• CHANGELOG.md: http://keepachangelog.com
• package.json: https://docs.npmjs.com/files/package.json

Example

All releases of gh-publish were created with gh-publish.

Config location

Platform | Location --- | --- OS X | ~/Library/Application Support/gh-publish/config.json Linux (XDG) | $XDG_CONFIG_HOME/gh-publish/config.json Linux (Legacy) | ~/.config/gh-publish/config.json Windows (> Vista) | %LOCALAPPDATA%/gh-publish/config.json Windows (XP, 2000) | %USERPROFILE%/Local Settings/Application Data/gh-publish/config.json

Motivation

There are packages that already do something like this, and they're great, but I want something that does this one thing really well and nothing else, leans heavily on standards in package.json and CHANGELOG.md, and can work both as a CLI tool and programmatically in node.

Contributing

Contributions welcome! Please read the contributing guidelines first.

Tests

gh-publish uses standard and tape for testing. You can run all tests with npm test.

License

ISC