semantic-release

https://semantic-release.gitbook.io/
Admin
semantic-release is a fully automated version management and package publishing tool that determines...
Tokens:19,753
Snippets:278
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Travis CLI

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Installs the Travis CI command-line interface.

```bash
$ gem install travis
```

--------------------------------

### Define plugin configuration options

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Example of how a user defines custom options in their release configuration file.

```js
{
  prepare: {
    path: "@semantic-release/my-special-plugin";
    message: "My cool release message";
  }
}
```

--------------------------------

### Configure pre-release branches

Source: https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration.md

Example configuration for defining a master branch and a beta pre-release branch.

```json
"branches": ["master", {"name": "beta", "prerelease": true}]
```

--------------------------------

### Configure semantic-release branches

Source: https://semantic-release.gitbook.io/semantic-release/usage/configuration.md

Examples showing how to define release branches using different configuration formats.

```json
{
  "release": {
    "branches": ["master", "next"]
  }
}
```

```json
{
  "branches": ["master", "next"]
}
```

```javascript
/**
 * @type {import('semantic-release').GlobalConfig}
 */
module.exports = {
  branches: ["master", "next"],
};
```

```javascript
/**
 * @type {import('semantic-release').GlobalConfig}
 */
export default {
  branches: ["master", "next"],
};
```

```bash
$ semantic-release --branches next
```

--------------------------------

### Install additional plugins via npm

Source: https://semantic-release.gitbook.io/semantic-release/usage/plugins.md

Command to install extra plugins as development dependencies.

```bash
$ npm install @semantic-release/git @semantic-release/changelog -D
```

--------------------------------

### View plugin log output

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Example of the formatted output generated by the plugin logger.

```text
[3:24:04 PM] [semantic-release] [PLUGIN_PACKAGE_NAME] › ℹ  Some message from plugin.
```

--------------------------------

### Configure package.json for local installation

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/jenkins-ci.md

Required configuration when installing semantic-release locally within a project.

```json
{
  "devDependencies": {
    "semantic-release": "^18.0.0"
  }
}
```

--------------------------------

### Declare plugins in configuration

Source: https://semantic-release.gitbook.io/semantic-release/usage/plugins.md

Configuration examples for defining the plugin list. Note that defining this list overrides the default plugins entirely.

```json
{
  "plugins": ["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/npm"]
}
```

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/git"
  ]
}
```

--------------------------------

### Configure Node.js setup in GitHub Actions

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions.md

Avoid using the registry-url option in setup-node to prevent conflicts with semantic-release authentication. Use the recommended configuration to allow semantic-release to manage npm authentication.

```yaml
# ❌ Don't do this - can cause conflicts with semantic-release
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "lts/*"
    registry-url: "https://registry.npmjs.org"

# ✅ Do this instead - let semantic-release handle npm authentication
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "lts/*"
```

--------------------------------

### Example releases array structure

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api.md

An array of release objects showing the expected properties for GitHub and npm releases.

```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'
   }
 ]
```

--------------------------------

### Perform a documentation query via HTTP GET

Source: https://semantic-release.gitbook.io/semantic-release/llms.txt

Use this request to ask a specific question about the documentation. The 'ask' parameter is required, while 'goal' is optional for better context.

```http
GET https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Configure semantic-release with @semantic-release/exec

Source: https://semantic-release.gitbook.io/semantic-release/support/faq.md

Example configuration for publishing non-Node packages by disabling default npm plugins and using shell commands for preparation and publishing.

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/github",
    [
      "@semantic-release/exec",
      {
        "prepareCmd": "set-version ${nextRelease.version}",
        "publishCmd": "publish-package"
      }
    ]
  ]
}
```

--------------------------------

### Switch Node version with nvm

Source: https://semantic-release.gitbook.io/semantic-release/support/node-version.md

Use nvm to install and switch to the latest LTS version of Node before executing semantic-release.

```bash
$ nvm install 'lts/*' && npx semantic-release
```

--------------------------------

### Travis CI Configuration for SSH

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Example configuration for the .travis.yml file to decrypt and add the SSH key.

```yaml
before_install:
  # Decrypt the git_deploy_key.enc key into /tmp/git_deploy_key
  - openssl aes-256-cbc -K $encrypted_KKKKKKKKKKKK_key -iv $encrypted_VVVVVVVVVVVV_iv -in git_deploy_key.enc -out /tmp/git_deploy_key -d
  # Make sure only the current user can read the private key
  - chmod 600 /tmp/git_deploy_key
  # Create a script to return the passphrase environment variable to ssh-add
  - echo 'echo ${SSH_PASSPHRASE}' > /tmp/askpass && chmod +x /tmp/askpass
  # Start the authentication agent
  - eval "$(ssh-agent -s)"
  # Add the key to the authentication agent
  - DISPLAY=":0.0" SSH_ASKPASS="/tmp/askpass" setsid ssh-add /tmp/git_deploy_key </dev/null
```

--------------------------------

### Verify package name availability

Source: https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md

Commands to install and use npm-name-cli to check if a package name is already taken.

```bash
$ npm install --global npm-name-cli
$ npm-name <package-name>
```

--------------------------------

### GET /semantic-release/support/troubleshooting.md

Source: https://semantic-release.gitbook.io/semantic-release/llms.txt

Perform a query against the documentation index to receive a direct answer, relevant excerpts, and sources based on a natural language question.

```APIDOC
## GET /semantic-release/support/troubleshooting.md

### Description
Queries the documentation index to retrieve answers to specific questions.

### Method
GET

### Endpoint
https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question written in natural language.
- **goal** (string) - Optional - The broader end goal to help tailor the response.
```

--------------------------------

### Example lastRelease object

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api.md

Structure of the lastRelease object returned in the result, representing the most recent release metadata.

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

--------------------------------

### Identify npm E403 error

Source: https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md

Example of the error output received when lacking npm publishing permissions.

```bash
npm ERR! publish Failed PUT 403
npm ERR! code E403
npm ERR! You do not have permission to publish "<package-name>". Are you logged in as the correct user? : <package-name>
```

--------------------------------

### Git history for 4.0.0 beta development

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

Visual representation of the repository history after starting work on a new major release version.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|  * feat: second feature # => v2.0.0-beta.2 on @beta
*  | fix: a fix # => v1.0.1 on @latest
|  | \
|  |  * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /|  |
*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
|  | /|
|  *  | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
| /|  |
*  |  | Merge branch beta into master/main # => v3.0.0 on @latest
| \|  |
|  *  | Merge branch master/main into beta
|  *  | feat: new feature # => v3.1.0-beta.1 on @beta
```

--------------------------------

### Configure branches and plugins for pre-releases

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

The default configuration for branches and plugins required to support pre-release channels like beta and alpha.

```javascript
branches: ['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]
```

```javascript
plugins: ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']
```

--------------------------------

### Expose verifyConditions lifecycle method

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Define the entry point in index.js to export the verifyConditions function for semantic-release.

```javascript
const verify = require("./src/verify");

let verified;

/**
 * Called by semantic-release during the verification step
 * @param {*} pluginConfig The semantic-release plugin config
 * @param {*} context The context provided by semantic-release
 */
async function verifyConditions(pluginConfig, context) {
  await verify(pluginConfig, context);
  verified = true;
}

module.exports = { verifyConditions };
```

--------------------------------

### semanticRelease(options, environment)

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api.md

The main entry point for the semantic-release library. It executes the release process based on the provided configuration and environment settings.

```APIDOC
## semanticRelease(options, environment)

### Description
Executes the semantic-release process programmatically. Returns a result object containing release details if a release was performed, or null if no release was published.

### Parameters
- **options** (Object) - Required - Configuration options including branches, repositoryUrl, extends, and plugin-specific settings.
- **environment** (Object) - Optional - Execution context including cwd, env variables, and custom stdout/stderr streams.

### Response
- **result** (Object|null) - Contains lastRelease, commits, nextRelease, and releases information if successful, otherwise null.
```

--------------------------------

### Run semantic-release with plugins via npx

Source: https://semantic-release.gitbook.io/semantic-release/usage/installation.md

Include additional plugins or presets when executing semantic-release via npx.

```sh
npx --package semantic-release --package @semantic-release/exec --package conventional-changelog-conventionalcommits semantic-release
```

--------------------------------

### Implement verification logic

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Create a verification module in src/verify.js to validate plugin configuration and throw errors if necessary.

```javascript
const AggregateError = require("aggregate-error");

/**
 * A method to verify that the user has given us a slack webhook url to post to
 */
module.exports = async (pluginConfig, context) => {
  const { logger } = context;
  const errors = [];

  // Throw any errors we accumulated during the validation
  if (errors.length > 0) {
    throw new AggregateError(errors);
  }
};
```

--------------------------------

### Configure .gitlab-ci.yml for general projects

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/gitlab-ci.md

A minimal configuration for running semantic-release on specific branches, including necessary system dependencies.

```yaml
# The release pipeline will run only on the master/main branch a commit is triggered
stages:
  - release

release:
  image: node:10-buster-slim
  stage: release
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
    - npm install -g semantic-release @semantic-release/gitlab
  script:
    - semantic-release
  rules:
    - if: $CI_COMMIT_BRANCH == "master" # or main

release:
  image: node:12-buster-slim
  stage: release
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
    - npm install -g semantic-release @semantic-release/gitlab
  script:
    - semantic-release
  rules:
    - if: $CI_COMMIT_BRANCH == "master" # or main
```

--------------------------------

### Expand branch configuration with prerelease templates

Source: https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration.md

Shows how the prerelease property is expanded using Lodash templates based on the branch name.

```js
{
  branches: [
    { name: "master" },
    { name: "pre/rc", channel: "pre/rc", prerelease: "rc" }, // `prerelease` is built with the template `${name.replace(/^pre\//g, "")}`
    { name: "beta", channel: "beta", prerelease: true }, // `prerelease` is set to `beta` as it is the value of `name`
  ];
}
```

--------------------------------

### Run semantic-release with npx

Source: https://semantic-release.gitbook.io/semantic-release/usage/installation.md

Execute semantic-release directly in the CI environment using npx.

```sh
npx semantic-release
```

--------------------------------

### Invoke semantic-release programmatically

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api.md

Demonstrates how to call the semantic-release function with custom configuration, environment variables, and stream buffers for output capture.

```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);
}
```

--------------------------------

### Configure .gitlab-ci.yml for Node projects

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/gitlab-ci.md

A minimal configuration for running tests on multiple Node versions and executing semantic-release in a release stage.

```yaml
# The release pipeline will run only if all jobs in the test pipeline are successful
stages:
  - test
  - release

before_script:
  - npm install

node:10:
  image: node:10
  stage: test
  script:
    - npm test

node:12:
  image: node:12
  stage: test
  script:
    - npm test

publish:
  image: node:12
  stage: release
  script:
    - npx semantic-release
```

--------------------------------

### Login to Travis CLI

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Authenticates the local environment with Travis CI.

```bash
$ travis login
```

--------------------------------

### Configure Jenkinsfile for Node.js

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/jenkins-ci.md

A minimal Declarative Pipeline configuration for running semantic-release after successful tests.

```groovy
// The release stage in the pipeline will run only if the test stage in the pipeline is successful
pipeline {
    agent any
    environment {
        GH_TOKEN  = credentials('some-id')
    }
    stages {
        stage('Test') {
            steps {
                sh '''
                # Configure your test steps here (checkout, npm install, tests etc)
                npm install
                npm test
                '''
            }
        }
        stage('Release') {
            tools {
                nodejs "node LTS"
            }
            steps {
                sh '''
                # Run optional required steps before releasing
                npx semantic-release
                '''
            }
        }
    }
}
```

--------------------------------

### Run semantic-release locally

Source: https://semantic-release.gitbook.io/semantic-release/support/faq.md

Execute semantic-release on a local machine by bypassing CI checks and providing necessary authentication tokens.

```bash
$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci
```

--------------------------------

### List default semantic-release plugins

Source: https://semantic-release.gitbook.io/semantic-release/usage/plugins.md

The default plugins included with semantic-release, listed in their execution order.

```text
"@semantic-release/commit-analyzer"
"@semantic-release/release-notes-generator"
"@semantic-release/npm"
"@semantic-release/github"
```

--------------------------------

### Check npm package versions

Source: https://semantic-release.gitbook.io/semantic-release/support/faq.md

Use the npm CLI to verify the current version tags for a package directly from the registry.

```shell
npm dist-tags ls <package-name>
```

--------------------------------

### Configure exec plugin for build scripts

Source: https://semantic-release.gitbook.io/semantic-release/support/faq.md

Use the @semantic-release/exec plugin to run custom build scripts during the prepare step, passing the next release version as an argument.

```json
{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    [
      "@semantic-release/exec",
      {
        "prepareCmd": "./my-build-script.sh ${nextRelease.version}"
      }
    ]
  ]
}
```

--------------------------------

### Default plugins configuration

Source: https://semantic-release.gitbook.io/semantic-release/usage/configuration.md

The default list of plugins executed in series by semantic-release.

```javascript
['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']
```

--------------------------------

### Execute semantic-release with npx

Source: https://semantic-release.gitbook.io/semantic-release/support/node-version.md

Use npx to run semantic-release using a specific version of Node.

```bash
$ npx -p node@v24 -c "npx semantic-release"
```

--------------------------------

### Git history after first pre-release

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

Visual representation of the Git history after pushing the first feature to the beta branch.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature 

 BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
```

--------------------------------

### Re-create git notes

Source: https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md

Commands to restore semantic-release notes for specific release channels.

```bash
git notes --ref semantic-release add -f -m '{"channels":["beta"]}' v2.0.0-beta.1
```

```bash
git notes --ref semantic-release add -f -m '{"channels":[null, "beta"]}'
```

--------------------------------

### Git history for 3.0.0 alpha to beta promotion

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

Visual representation of the repository history after merging the alpha branch into the beta branch.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature 

 BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|  * feat: second feature # => v2.0.0-beta.2 on @beta
*  | fix: a fix # => v1.0.1 on @latest
|  | \
|  |  * feat: first feature of other release 

 BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /|  |
*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
|  | /|
|  *  | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
```

--------------------------------

### Configure actions/checkout for semantic-release

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions.md

Set persist-credentials to false in the checkout step to prevent the default GITHUB_TOKEN from interfering with custom authentication.

```yaml
- name: Checkout
  uses: actions/checkout@v2
  with:
    fetch-depth: 0
    persist-credentials: false # <--- this
```

--------------------------------

### Configure .travis.yml for non-JavaScript projects

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/travis.md

A minimal configuration using build stages to run semantic-release after tests. It utilizes nvm to ensure a Node.js environment is available for the release process.

```yaml
language: go

go:
  - 1.6
  - 1.7

jobs:
  include:
    # Define the release stage that runs semantic-release
    - stage: release
      # Advanced: optionally overwrite your default `script` step to skip the tests
      # script:
      #   - make
      deploy:
        provider: script
        skip_cleanup: true
        script:
          # Use nvm to install and use the Node LTS version (nvm is installed on all Travis images)
          - nvm install lts/*
          - npx semantic-release
        on:
          all_branches: true
```

--------------------------------

### Configure .travis.yml for multiple Node.js jobs

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/travis.md

Defines a release stage in Travis CI to execute semantic-release after test jobs complete, using Node.js LTS.

```yaml
language: node_js

node_js:
  - 14
  - 16

jobs:
  include:
    # Define the release stage that runs semantic-release
    - stage: release
      node_js: lts/*
      # Advanced: optionally overwrite your default `script` step to skip the tests
      # script: skip
      deploy:
        provider: script
        skip_cleanup: true
        script:
          - npx semantic-release
```

--------------------------------

### Implement plugin logging

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Access the logger from the plugin context to output status messages during execution.

```js
const { logger } = context;

logger.log('Some message from plugin.').
```

--------------------------------

### Define a release workflow for Node.js projects

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions.md

A minimal GitHub Actions workflow configuration to run semantic-release on push events to the main or master branch.

```yaml
name: Release
on:
  push:
    branches:
      - master # or main

permissions:
  contents: read # for checkout

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write # to be able to publish a GitHub release
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for trusted publishing and npm provenance
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "lts/*"
      - name: Install dependencies
        run: npm clean-install
      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
        run: npm audit signatures
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release
```

--------------------------------

### Git history after second pre-release

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

Visual representation of the Git history after pushing a second feature to the beta branch.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature 

 BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|  * feat: second feature # => v2.0.0-beta.2 on @beta
```

--------------------------------

### Git history for 2.0.0 beta release

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

Visual representation of the repository history after merging the beta branch into master/main.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature 

 BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|  * feat: second feature # => v2.0.0-beta.2 on @beta
*  | fix: a fix # => v1.0.1 on @latest
|  | \
|  |  * feat: first feature of other release 

 BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /|  |
*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
```

--------------------------------

### Git history for 3.0.0 beta release

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/pre-releases.md

Visual representation of the repository history after merging the beta branch into master/main.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|  * feat: second feature # => v2.0.0-beta.2 on @beta
*  | fix: a fix # => v1.0.1 on @latest
|  | \
|  |  * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
|  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
| /|  |
*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
|  | /|
|  *  | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
| /|  |
*  |  | Merge branch beta into master/main # => v3.0.0 on @latest
```

--------------------------------

### Committing encrypted files to the repository

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Add the encrypted key and updated configuration to version control.

```bash
$ git add git_deploy_key.enc .circleci/config.yml
$ git commit -m "ci(circle): Add the encrypted private ssh key"
$ git push
```

--------------------------------

### Repository Git history visualization

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/maintenance-releases.md

A visual representation of commit history across multiple branches and release tags.

```text
* feat: initial commit # => v1.0.0 on @latest
| \
*  | feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required # => v2.0.0 on @latest
|  | \
|  *  | feat: a feature # => v1.1.0 on @1.x
|  |  * fix: a fix # => v1.0.1 on @1.0.x
|  | /|
|  *  | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
| /|  |
*  |  | Merge branch 1.x into master/main # => v2.1.0 on @latest
*  |  | fix: another fix # => v2.1.1 on @latest
|  |  |
|  *  | fix: another fix # => v1.1.2 on @1.x
```

--------------------------------

### Encrypt Private Key for Travis

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Encrypts the private key file for secure storage in the CI environment.

```bash
$ travis encrypt-file git_deploy_key
```

--------------------------------

### Initial release Git history

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/maintenance-releases.md

Represents the Git commit history for the initial project release resulting in version 1.0.0.

```text
* feat: initial commit # => v1.0.0 on @latest
```

--------------------------------

### Push git notes

Source: https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md

Command to force push the restored notes to the remote repository.

```bash
git push --force origin refs/notes/semantic-release
```

--------------------------------

### semanticRelease(options, config)

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api.md

Executes the semantic-release process programmatically. Returns a Promise that resolves to a Result object containing release details or false if no release occurred.

```APIDOC
## semanticRelease(options, config)

### Description
Runs semantic-release and returns a Promise that resolves to a Result object if a release is published, or false if no release is published.

### Parameters
- **options** (Object) - Optional - semantic-release core or plugin options. These take precedence over configuration files.
- **config** (Object) - Optional - Configuration specific for API usage.
  - **cwd** (String) - Optional - The current working directory to use (default: process.cwd()).
  - **env** (Object) - Optional - Environment variables to use (default: process.env).
  - **stdout** (stream.Writable) - Optional - Writable stream for logs (default: process.stdout).
  - **stderr** (stream.Writable) - Optional - Writable stream for errors (default: process.stderr).

### Returns
- **Result** (Object|Boolean) - An object containing `lastRelease`, `nextRelease`, `commits`, and `releases` if a release is published, or `false` if no release was published.
```

--------------------------------

### Configure repository_dispatch trigger

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions.md

Define a workflow that listens for the semantic-release event type.

```yaml
name: Release
on:
  repository_dispatch:
    types: [semantic-release]
jobs:
# ...
```

--------------------------------

### Trigger release via HTTP request

Source: https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions.md

Use curl to send a repository_dispatch event to trigger the release workflow.

```bash
$ curl -v -H "Accept: application/vnd.github.everest-preview+json" -H "Authorization: token ${GITHUB_TOKEN}" https://api.github.com/repos/[org-name-or-username]/[repository]/dispatches -d '{ "event_type": "semantic-release" }'
```

--------------------------------

### Git history after porting a feature to next

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/distribution-channels.md

Visual representation of the repository history after merging master/main into the next branch.

```text
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
|  * feat: a big feature 

 BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|  * fix: fix something on the big feature # => v2.0.1 on @next
*  | feat: a small feature # => v1.1.0 on @latest
|  * Merge branch master/main into next # => v2.1.0 on @next
```

--------------------------------

### Git history after adding a version to latest

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/distribution-channels.md

Visual representation of the repository history after merging the next branch into master/main.

```text
* feat: initial commit # => v1.0.0 on @latest
* fix: a fix # => v1.0.1 on @latest
| \
|  * feat: a big feature 

 BREAKING CHANGE: it breaks something # => v2.0.0 on @next
|  * fix: fix something on the big feature # => v2.0.1 on @next
*  | feat: a small feature # => v1.1.0 on @latest
|  * Merge branch master/main into next # => v2.1.0 on @next
| /|
*  | Merge branch next into master/main # => v2.1.0 on @latest
```

--------------------------------

### Renovate configuration for npx updates

Source: https://semantic-release.gitbook.io/semantic-release/usage/installation.md

Configure Renovate to automatically update the semantic-release version used in npx commands within CI workflows.

```json
{
  "customManagers": [
    {
      "customType": "regex",
      "description": "Update semantic-release version used by npx",
      "managerFilePatterns": ["^\.github/workflows/[^/]+\.ya?ml$"],
      "matchStrings": ["\srun: npx semantic-release@(?<currentValue>.*?)\s"],
      "datasourceTemplate": "npm",
      "depNameTemplate": "semantic-release"
    }
  ]
}
```

--------------------------------

### Encrypting the SSH private key

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Use OpenSSL to encrypt the private key with AES-256, noting the generated key and IV for later use in environment variables.

```bash
$ openssl aes-256-cbc -e -p -in git_deploy_key -out git_deploy_key.enc -K `openssl rand -hex 32` -iv `openssl rand -hex 16`
salt=SSSSSSSSSSSSSSSS
key=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
iv =VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV
```

--------------------------------

### Re-create git tags

Source: https://semantic-release.gitbook.io/semantic-release/support/troubleshooting.md

Command to recreate a tag pointing to the new commit hash.

```bash
git tag v2.0.0-beta.1 abcdef0
```

--------------------------------

### Cherry-pick a fix to a maintenance branch

Source: https://semantic-release.gitbook.io/semantic-release/recipes/release-workflow/maintenance-releases.md

Use these commands to switch to the maintenance branch and apply a specific commit from the main branch.

```bash
git checkout 1.x && git cherry-pick <sha of fix: another fix>
```

--------------------------------

### Commit Encrypted Key

Source: https://semantic-release.gitbook.io/semantic-release/recipes/git-hosted-services/git-auth-ssh-keys.md

Stages and commits the encrypted key and configuration file to the repository.

```bash
$ git add git_deploy_key.enc .travis.yml
$ git commit -m "ci(travis): Add the encrypted private ssh key"
$ git push
```

--------------------------------

### Default branches configuration

Source: https://semantic-release.gitbook.io/semantic-release/usage/configuration.md

The default branches configuration used by semantic-release to determine release targets.

```javascript
['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]
```

--------------------------------

### Access environment variables from context

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Retrieving environment variables like GITHUB_TOKEN from the context object during plugin execution.

```js
const { env } = context;

if (env.GITHUB_TOKEN) {
  //...
}
```

--------------------------------

### Validate plugin configuration options

Source: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin.md

Accessing the pluginConfig object to verify that specific options are provided.

```js
const { message } = pluginConfig;

if (message.length) {
  //...
}
```

--------------------------------

### Configure npm access level

Source: https://semantic-release.gitbook.io/semantic-release/support/faq.md

Set the npm package access level using either the .npmrc file or the package.json configuration.

```rc
access=public
```

```json
{
  "publishConfig": {
    "access": "public"
  }
}
```

--------------------------------

### Verify and Add Git Tags

Source: https://semantic-release.gitbook.io/semantic-release/usage/configuration.md

Commands to check if a specific commit is included in the release branch history and to manually tag a commit if the tag is missing.

```bash
# Make sure the commit 1234567 is in the release branch history
$ git branch --contains 1234567

# If the commit is not in the branch history it means that either:
# - you use a different branch than the one your release from before
# - or the commit sha has been rewritten (with git rebase)
# In both cases you need to configure your repository to have the last release commit in the history of the release branch

# List the tags for the commit 1234567
$ git tag --contains 1234567

# If v1.1.0 is not in the list you add it with
$ git tag v1.1.0 1234567
$ git push origin v1.1.0
```
Tokens:
Raw