@gr2m/semantic-release-github v5.4.0-beta.1-issue-182
@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 repositorypublic_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 Object
s 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 String
s 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
6 years ago