@semantic-release/github

semantic-release plugin to publish a GitHub release and comment on released Pull Requests/Issues.

Step	Description
`verifyConditions`	Verify the presence and the validity of the authentication (set via environment variables) and the assets option configuration.
`publish`	Publish a GitHub release, optionally uploading file assets.
`success`	Add a comment to each GitHub Issue or Pull Request resolved by the release and close issues previously open by the `fail` step.
`fail`	Open or update a GitHub Issue with informations about the errors that caused the release to fail.

Install

$ npm install @semantic-release/github -D

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/github", {
      "assets": [
        {"path": "dist/asset.min.css", "label": "CSS distribution"},
        {"path": "dist/asset.min.js", "label": "JS distribution"}
      ]
    }],
  ]
}

With this example GitHub releases will be published with the file dist/asset.min.css and dist/asset.min.js.

Configuration

GitHub authentication

The GitHub authentication configuration is required and can be set via environment variables.

Follow the Creating a personal access token for the command line documentation to obtain an authentication token. The token has to be made available in your CI environment via the GH_TOKEN environment variable. The user associated with the token must have push permission to the repository.

When creating the token, the minimum required scopes are:

repo for a private repository
public_repo for a public repository

Environment variables

Variable	Description
`GH_TOKEN` or `GITHUB_TOKEN`	Required. The token used to authenticate with GitHub.
`GH_URL` or `GITHUB_URL`	The GitHub Enterprise endpoint.
`GH_PREFIX` or `GITHUB_PREFIX`	The GitHub Enterprise API prefix.

Options

Option	Description	Default
`githubUrl`	The GitHub Enterprise endpoint.	`GH_URL` or `GITHUB_URL` environment variable.
`githubApiPathPrefix`	The GitHub Enterprise API prefix.	`GH_PREFIX` or `GITHUB_PREFIX` environment variable.
`proxy`	The proxy to use to access the GitHub API. See proxy.	`HTTP_PROXY` environment variable.
`assets`	An array of files to upload to the release. See assets.	-
`successComment`	The comment to add to each issue and pull request resolved by the release. Set to `false` to disable commenting on issues and pull requests. See successComment.	`:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)`
`failComment`	The content of the issue created when a release fails. Set to `false` to disable opening an issue when a release fails. See failComment.	Friendly message with links to semantic-release documentation and support, with the list of errors that caused the release to fail.
`failTitle`	The title of the issue created when a release fails. Set to `false` to disable opening an issue when a release fails.	`The automated release is failing 🚨`
`labels`	The labels to add to the issue created when a release fails. Set to `false` to not add any label.	`['semantic-release']`
`assignees`	The assignees to add to the issue created when a release fails.	-
`releasedLabels`	The labels to add to each issue and pull request resolved by the release. Set to `false` to not add any label.	`['released']`

proxy

Can be a the proxy URL or and Object with the following properties:

Property	Description	Default
`host`	Required. Proxy host to connect to.	-
`port`	Required. Proxy port to connect to.	File name extracted from the `path`.
`secureProxy`	If `true`, then use TLS to connect to the proxy.	`false`
`headers`	Additional HTTP headers to be sent on the HTTP CONNECT method.	-

See node-https-proxy-agent and node-http-proxy-agent for additional details.

proxy examples

'http://168.63.76.32:3128': use the proxy running on host 168.63.76.32 and port 3128 for each GitHub API request. {host: '168.63.76.32', port: 3128, headers: {Foo: 'bar'}}: use the proxy running on host 168.63.76.32 and port 3128 for each GitHub API request, setting the Foo header value to bar.

assets

Can be a glob or and Array of globs and Objects with the following properties:

Property	Description	Default
`path`	Required. A glob to identify the files to upload.	-
`name`	The name of the downloadable file on the GitHub release.	File name extracted from the `path`.
`label`	Short description of the file displayed on the GitHub release.	-

Each entry in the assets Array is globbed individually. A glob can be a String ("dist/**/*.js" or "dist/mylib.js") or an Array of Strings that will be globbed together (["dist/**", "!**/*.css"]).

If a directory is configured, all the files under this directory and its children will be included.

Note: If a file has a match in assets it will be included even if it also has a match in .gitignore.

assets examples

'dist/*.js': include all the js files in the dist directory, but not in its sub-directories.

[['dist', '!**/*.css']]: include all the files in the dist directory and its sub-directories excluding the css files.

[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}]: include the dist/MyLibrary.js and dist/MyLibrary.css files, and label them MyLibrary JS distribution and MyLibrary CSS distribution in the GitHub release.

[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]: include all the js and css files in the dist directory and its sub-directories excluding the minified version, plus the build/MyLibrary.zip file and label it MyLibrary in the GitHub release.

successComment

The message for the issue comments is generated with Lodash template. The following variables are available:

Parameter	Description
`branch`	The branch from which the release is done.
`lastRelease`	`Object` with `version`, `gitTag` and `gitHead` of the last release.
`nextRelease`	`Object` with `version`, `gitTag`, `gitHead` and `notes` of the release being done.
`commits`	`Array` of commit `Object`s with `hash`, `subject`, `body` `message` and `author`.
`releases`	`Array` with a release `Object`s for each release published, with optional release data such as `name` and `url`.
`issue`	A GitHub API pull request object for pull requests related to a commit, or an `Object` with the `number` property for issues resolved via keywords

successComment examples

The successComment This ${issue.pull_request ? 'pull request' : 'issue'} is included in version ${nextRelease.version} will generate the comment:

This pull request is included in version 1.0.0

failComment

The message for the issue content is generated with Lodash template. The following variables are available:

Parameter	Description
`branch`	The branch from which the release had failed.
`errors`	An `Array` of SemanticReleaseError. Each error has the `message`, `code`, `pluginName` and `details` properties. `pluginName` contains the package name of the plugin that threw the error. `details` contains a informations about the error formatted in markdown.

failComment examples

The failComment This release from branch ${branch} had failed due to the following errors:\n- ${errors.map(err => err.message).join('\\n- ')} will generate the comment:

This release from branch master had failed due to the following errors:

Error message 1

Error message 2

Doginal/github