JavaScript API
Usage
API
semanticRelease([options], [config]) => Promise
Run semantic-release and returns a Promise
that resolves to a Result object.
options
Type: Object
semantic-release options.
Can be used to set any core option or plugin options.
Each option, will take precedence over options configured in the configuration file and shareable configurations.
config
Type: Object
semantic-release configuration specific for API usage.
cwd
Type: String
Default: process.cwd()
The current working directory to use. It should be configured to the root of the Git repository to release from.
It allows to run semantic-release from a specific path without having to change the local process cwd
with process.chdir()
.
env
Type: Object
Default: process.env
The environment variables to use.
It allows to run semantic-release with specific environment variables without having to modify the local process.env
.
stdout
Type: stream.Writable
Default: process.stdout
The writable stream used to log information.
It allows to configure semantic-release to write logs to a specific stream rather than the local process.stdout
.
stderr
Type: stream.Writable
Default: process.stderr
The writable stream used to log errors.
It allows to configure semantic-release to write errors to a specific stream rather than the local process.stderr
.
Result
Type: Object
Boolean
An object with lastRelease
, nextRelease
, commits
and releases
if a release is published or false
if no release was published.
lastRelease
Type: Object
Information related to the last release found:
Name | Type | Description |
---|---|---|
version |
| The version of the last release. |
gitHead |
| The sha of the last commit being part of the last release. |
gitTag |
| The Git tag associated with the last release. |
channel |
| The distribution channel on which the last release was initially made available ( |
Note: If no previous release is found, lastRelease
will be an empty Object
.
Example:
commits
Type: Array<Object>
The list of commit(s) included in the new release. Each commit object has the following properties:
Name | Type | Description |
---|---|---|
commit |
| The commit abbreviated and full hash. |
commit.long |
| The commit hash. |
commit.short |
| The commit abbreviated hash. |
tree |
| The commit abbreviated and full tree hash. |
tree.long |
| The commit tree hash. |
tree.short |
| The commit abbreviated tree hash. |
author |
| The commit author information. |
author.name |
| The commit author name. |
author.email |
| The commit author email. |
author.short |
| The commit author date. |
committer |
| The committer information. |
committer.name |
| The committer name. |
committer.email |
| The committer email. |
committer.short |
| The committer date. |
subject |
| The commit subject. |
body |
| The commit body. |
message |
| The commit full message ( |
hash |
| The commit hash. |
committerDate |
| The committer date. |
Example:
nextRelease
Type: Object
Information related to the newly published release:
Name | Type | Description |
---|---|---|
type |
| The semver type of the release ( |
version |
| The version of the new release. |
gitHead |
| The sha of the last commit being part of the new release. |
gitTag |
| The Git tag associated with the new release. |
notes |
| The release notes for the new release. |
channel |
| The distribution channel on which the next release will be made available ( |
Example:
releases
Type: Array<Object>
The list of releases published or made available to a distribution channel. Each release object has the following properties:
Name | Type | Description |
---|---|---|
name |
| Optional. The release name, only if set by the corresponding |
url |
| Optional. The release URL, only if set by the corresponding |
type |
| The semver type of the release ( |
version |
| The version of the release. |
gitHead |
| The sha of the last commit being part of the release. |
gitTag |
| The Git tag associated with the release. |
notes |
| The release notes for the release. |
pluginName |
| The name of the plugin that published the release. |
channel |
| The distribution channel on which the release is available ( |
Example:
Last updated