Back to Semantic Release

JavaScript API

docs/developer-guide/js-api.md

25.0.311.6 KB
Original Source

JavaScript API

Usage

js
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",
        "main",
        "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<Result>

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:

NameTypeDescription
versionStringThe version of the last release.
gitHeadStringThe sha of the last commit being part of the last release.
gitTagStringThe Git tag associated with the last release.
channelStringThe distribution channel on which the last release was initially made available (undefined for the default distribution channel).

Note: If no previous release is found, lastRelease will be an empty Object.

Example:

js
{
  gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
  version: '1.0.0',
  gitTag: 'v1.0.0',
  channel: 'next'
}

commits

Type: Array<Object>

The list of commit(s) included in the new release.

Each commit object has the following properties:

NameTypeDescription
commitObjectThe commit abbreviated and full hash.
commit.longStringThe commit hash.
commit.shortStringThe commit abbreviated hash.
treeObjectThe commit abbreviated and full tree hash.
tree.longStringThe commit tree hash.
tree.shortStringThe commit abbreviated tree hash.
authorObjectThe commit author information.
author.nameStringThe commit author name.
author.emailStringThe commit author email.
author.shortStringThe commit author date.
committerObjectThe committer information.
committer.nameStringThe committer name.
committer.emailStringThe committer email.
committer.shortStringThe committer date.
subjectStringThe commit subject.
bodyStringThe commit body.
messageStringThe commit full message (subject and body).
hashStringThe commit hash.
committerDateStringThe committer date.

Example:

js
[
  {
    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:

NameTypeDescription
typeStringThe semver type of the release (patch, minor or major).
versionStringThe version of the new release.
gitHeadStringThe sha of the last commit being part of the new release.
gitTagStringThe Git tag associated with the new release.
notesStringThe release notes for the new release.
channelStringThe distribution channel on which the next release will be made available (undefined for the default distribution channel).

Example:

js
{
  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:

NameTypeDescription
nameStringOptional. The release name, only if set by the corresponding publish plugin.
urlStringOptional. The release URL, only if set by the corresponding publish plugin.
typeStringThe semver type of the release (patch, minor or major).
versionStringThe version of the release.
gitHeadStringThe sha of the last commit being part of the release.
gitTagStringThe Git tag associated with the release.
notesStringThe release notes for the release.
pluginNameStringThe name of the plugin that published the release.
channelStringThe distribution channel on which the release is available (undefined for the default distribution channel).

Example:

js
[
  {
    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'
   }
 ]