semantic-release
AboutGitHubNeed Help?
master
master
  • README
  • Usage
    • Getting started
    • Installation
    • CI Configuration
    • Configuration
    • Plugins
    • Release Workflow configuration
    • Shareable configurations
  • Extending
    • Plugins
    • Shareable configuration
  • Recipes
    • CI configurations
      • CircleCI 2.0
      • Travis CI
      • GitLab CI
      • GitHub Actions
      • Jenkins CI
    • Git hosted services
      • Git authentication with SSH keys
    • Release Workflow
      • Publishing on distribution channels
      • Publishing maintenance releases
      • Publishing pre-releases
  • Developer guide
    • JavaScript API
    • Plugin development
    • Shareable configuration development
  • Support
    • Resources
    • Frequently Asked Questions
    • Troubleshooting
    • Node version requirement
    • Node Support Policy
    • Git version requirement
Powered by GitBook
On this page
  • Usage
  • API
  • semanticRelease([options], [config]) => Promise
  • Result
Edit on GitHub
  1. Developer guide

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",
        "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

options

Type: Object

semantic-release options.

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

It allows to configure semantic-release to write logs to a specific stream rather than the local process.stdout.

stderr

It allows to configure semantic-release to write errors to a specific stream rather than the local process.stderr.

Result

Type: Object Boolean

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

channel

String

The 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:

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

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: 'me@email.com',
      date: 2018-07-22T20:52:44.000Z
    },
    committer: {
      name: 'Me',
      email: 'me@email.com',
      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

version

String

The version of the new release.

gitHead

String

The sha of the last commit being part of the new release.

gitTag

String

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

version

String

The version of the release.

gitHead

String

The sha of the last commit being part of the release.

gitTag

String

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'
   }
 ]
PreviousPublishing pre-releasesNextPlugin development

Last updated 12 months ago

Run semantic-release and returns a Promise that resolves to a object.

Can be used to set any or .

Each option, will take precedence over options configured in the and .

Type: Default: process.stdout

The used to log information.

Type: Default: process.stderr

The used to log errors.

An object with , , and if a release is published or false if no release was published.

The associated with the last release.

The type of the release (patch, minor or major).

The associated with the new release.

The type of the release (patch, minor or major).

The associated with the release.

stream.Writable
writable stream
stream.Writable
writable stream
Result
lastRelease
nextRelease
commits
releases
Git tag
semver
Git tag
semver
Git tag
plugin options
core option
configuration file
shareable configurations