JavaScript API

Usage
const semanticRelease = require("semantic-release");
const { WritableStreamBuffer } = require("stream-buffers");
​
const stdoutBuffer = new WritableStreamBuffer();
const stderrBuffer = new WritableStreamBuffer();
​
try {
  const result = await semanticRelease(
    {
      // Core options
      branches: [
        "+([0-9])?(.{+([0-9]),x}).x",
        "master",
        "next",
        "next-major",
        { name: "beta", prerelease: true },
        { name: "alpha", prerelease: true },
      ],
      repositoryUrl: "https://github.com/me/my-package.git",
      // Shareable config
      extends: "my-shareable-config",
      // Plugin options
      githubUrl: "https://my-ghe.com",
      githubApiPathPrefix: "/api-prefix",
    },
    {
      // Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
      cwd: "/path/to/git/repo/root",
      // Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
      env: { ...process.env, MY_ENV_VAR: "MY_ENV_VAR_VALUE" },
      // Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
      stdout: stdoutBuffer,
      stderr: stderrBuffer,
    }
  );
​
  if (result) {
    const { lastRelease, commits, nextRelease, releases } = result;
​
    console.log(
      `Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`
    );
​
    if (lastRelease.version) {
      console.log(`The last release was "${lastRelease.version}".`);
    }
​
    for (const release of releases) {
      console.log(`The release was published with plugin "${release.pluginName}".`);
    }
  } else {
    console.log("No release published.");
  }
​
  // Get stdout and stderr content
  const logs = stdoutBuffer.getContentsAsString("utf8");
  const errors = stderrBuffer.getContentsAsString("utf8");
} catch (err) {
  console.error("The automated release failed with %O", err);
}
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

And 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
String
The version of the last release.
gitHead
String
The sha of the last commit being part of the last release.
gitTag
String
The Git tag associated with the last release.
channel
String
The distribution channel on which the last release was initially made available (undefined for the default distribution channel).
Notes: If no previous release is found, lastRelease will be an empty Object.
Example:
{
  gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
  version: '1.0.0',
  gitTag: 'v1.0.0',
  channel: 'next'
}
commits
Type: Array<Object>
The list of commit included in the new release.
Each commit object has the following properties:
Name
Type
Description
commit
Object
The commit abbreviated and full hash.
commit.long
String
The commit hash.
commit.short
String
The commit abbreviated hash.
tree
Object
The commit abbreviated and full tree hash.
tree.long
String
The commit tree hash.
tree.short
String
The commit abbreviated tree hash.
author
Object
The commit author information.
author.name
String
The commit author name.
author.email
String
The commit author email.
author.short
String
The commit author date.
committer
Object
The committer information.
committer.name
String
The committer name.
committer.email
String
The committer email.
committer.short
String
The committer date.
subject
String
The commit subject.
body
String
The commit body.
message
String
The commit full message (subject and body).
hash
String
The commit hash.
committerDate
String
The committer date.
Example:
[
  {
    commit: {
      long: '68eb2c4d778050b0701136ca129f837d7ed494d2',
      short: '68eb2c4'
    },
    tree: {
      long: '7ab515d12bd2cf431745511ac4ee13fed15ab578',
      short: '7ab515d'
    },
    author: {
      name: 'Me',
      email: '[email protected]',
      date: 2018-07-22T20:52:44.000Z
    },
    committer: {
      name: 'Me',
      email: '[email protected]',
      date: 2018-07-22T20:52:44.000Z
    },
    subject: 'feat: a new feature',
    body: 'Description of the new feature',
    hash: '68eb2c4d778050b0701136ca129f837d7ed494d2',
    message: 'feat: a new feature\n\nDescription of the new feature',
    committerDate: 2018-07-22T20:52:44.000Z
  }
 ]
nextRelease
Type: Object
Information related to the newly published release:
Name
Type
Description
type
String
The semver type of the release (patch, minor or major).
version
String
The version of the new release.
gitHead
String
The sha of the last commit being part of the new release.
gitTag
String
The Git tag associated with the new release.
notes
String
The release notes for the new release.
channel
String
The distribution channel on which the next release will be made available (undefined for the default distribution channel).
Example:
{
  type: 'minor',
  gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2',
  version: '1.1.0',
  gitTag: 'v1.1.0',
  notes: 'Release notes for version 1.1.0...',
  channel : 'next'
}
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
String
Optional. The release name, only if set by the corresponding publish plugin.
url
String
Optional. The release URL, only if set by the corresponding publish plugin.
type
String
The semver type of the release (patch, minor or major).
version
String
The version of the release.
gitHead
String
The sha of the last commit being part of the release.
gitTag
String
The Git tag associated with the release.
notes
String
The release notes for the release.
pluginName
String
The name of the plugin that published the release.
channel
String
The distribution channel on which the release is available (undefined for the default distribution channel).
Example:
[
  {
    name: 'GitHub release',
    url: 'https://github.com/me/my-package/releases/tag/v1.1.0',
    type: 'minor',
    gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2',
    version: '1.1.0',
    gitTag: 'v1.1.0',
    notes: 'Release notes for version 1.1.0...',
    pluginName: '@semantic-release/github'
    channel: 'next'
  },
  {
    name: 'npm package (@latest dist-tag)',
    url: 'https://www.npmjs.com/package/my-package',
    type: 'minor',
    gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2',
    version: '1.1.0',
    gitTag: 'v1.1.0',
    notes: 'Release notes for version 1.1.0...',
    pluginName: '@semantic-release/npm'
    channel: 'next'
   }
 ]

Name	Type	Description
version	`String`	The version of the last release.
gitHead	`String`	The sha of the last commit being part of the last release.
gitTag	`String`	The Git tag associated with the last release.
channel	`String`	The distribution channel on which the last release was initially made available (`undefined` for the default distribution channel).

Name	Type	Description
commit	`Object`	The commit abbreviated and full hash.
commit.long	`String`	The commit hash.
commit.short	`String`	The commit abbreviated hash.
tree	`Object`	The commit abbreviated and full tree hash.
tree.long	`String`	The commit tree hash.
tree.short	`String`	The commit abbreviated tree hash.
author	`Object`	The commit author information.
author.name	`String`	The commit author name.
author.email	`String`	The commit author email.
author.short	`String`	The commit author date.
committer	`Object`	The committer information.
committer.name	`String`	The committer name.
committer.email	`String`	The committer email.
committer.short	`String`	The committer date.
subject	`String`	The commit subject.
body	`String`	The commit body.
message	`String`	The commit full message (`subject` and `body`).
hash	`String`	The commit hash.
committerDate	`String`	The committer date.

Name	Type	Description
type	`String`	The semver type of the release (`patch`, `minor` or `major`).
version	`String`	The version of the new release.
gitHead	`String`	The sha of the last commit being part of the new release.
gitTag	`String`	The Git tag associated with the new release.
notes	`String`	The release notes for the new release.
channel	`String`	The distribution channel on which the next release will be made available (`undefined` for the default distribution channel).

Name	Type	Description
name	`String`	Optional. The release name, only if set by the corresponding `publish` plugin.
url	`String`	Optional. The release URL, only if set by the corresponding `publish` plugin.
type	`String`	The semver type of the release (`patch`, `minor` or `major`).
version	`String`	The version of the release.
gitHead	`String`	The sha of the last commit being part of the release.
gitTag	`String`	The Git tag associated with the release.
notes	`String`	The release notes for the release.
pluginName	`String`	The name of the plugin that published the release.
channel	`String`	The distribution channel on which the release is available (`undefined` for the default distribution channel).

Last modified 18d ago