semantic-release/github

@semantic-release/github

semantic-release plugin to publish a GitHub release and comment on released Pull Requests/Issues.

Install

[!TIP] You do not need to directly depend on this package if you are using semantic-release. semantic-release already depends on this package, and defining your own direct dependency can result in conflicts when you update semantic-release.

$ npm install @semantic-release/github -D

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/github",
      {
        "assets": [
          { "path": "dist/asset.min.css", "label": "CSS distribution" },
          { "path": "dist/asset.min.js", "label": "JS distribution" }
        ]
      }
    ]
  ]
}

With this example GitHub releases will be published with the file dist/asset.min.css and dist/asset.min.js.

Configuration

GitHub authentication

The GitHub authentication configuration is required and can be set via environment variables.

Follow the Creating a personal access token for the command line documentation to obtain an authentication token. The token has to be made available in your CI environment via the GH_TOKEN environment variable. The user associated with the token must have push permission to the repository.

When creating the token, the minimum required scopes are:

• repo for a private repository
• public_repo for a public repository

Note on GitHub Actions: You can use the default token which is provided in the secret GITHUB_TOKEN. However releases done with this token will NOT trigger release events to start other workflows. If you have actions that trigger on newly created releases, please use a generated token for that and store it in your repository's secrets (any other name than GITHUB_TOKEN is fine).

When using the GITHUB_TOKEN, the minimum required permissions are:

• 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

Environment variables

Options

proxy

Can be false, a proxy URL or an Object with the following properties:

This plugin uses undici's ProxyAgent for modern proxy support, with backwards compatibility maintained through node-https-proxy-agent and node-http-proxy-agent. This ensures proxy functionality works with GitHub Enterprise Server environments behind corporate proxies.

proxy examples

'http://168.63.76.32:3128': use the proxy running on host 168.63.76.32 and port 3128 for each GitHub API request. {host: '168.63.76.32', port: 3128, headers: {Foo: 'bar'}}: use the proxy running on host 168.63.76.32 and port 3128 for each GitHub API request, setting the Foo header value to bar.

Note: This plugin now uses undici's ProxyAgent internally for enhanced proxy support, particularly beneficial for GitHub Enterprise Server environments behind corporate proxies. All existing proxy configurations remain fully compatible.

assets

Can be a glob or and Array of globs and Objects with the following properties:

Each entry in the assets Array is globbed individually. A glob can be a String ("dist/**/*.js" or "dist/mylib.js") or an Array of Strings that will be globbed together (["dist/**", "!**/*.css"]).

If a directory is configured, all the files under this directory and its children will be included.

The name and label for each assets are generated with Lodash template. The following variables are available:

Note: If a file has a match in assets it will be included even if it also has a match in .gitignore.

assets examples

'dist/*.js': include all the js files in the dist directory, but not in its sub-directories.

[['dist', '!**/*.css']]: include all the files in the dist directory and its sub-directories excluding the css files.

[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}]: include the dist/MyLibrary.js and dist/MyLibrary.css files, and label them MyLibrary JS distribution and MyLibrary CSS distribution in the GitHub release.

[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]: include all the js and css files in the dist directory and its sub-directories excluding the minified version, plus the build/MyLibrary.zip file and label it MyLibrary in the GitHub release.

[{path: 'dist/MyLibrary.js', name: 'MyLibrary-${nextRelease.gitTag}.js', label: 'MyLibrary JS (${nextRelease.gitTag}) distribution'}]: include the file dist/MyLibrary.js and upload it to the GitHub release with name MyLibrary-v1.0.0.js and label MyLibrary JS (v1.0.0) distribution which will generate the link:

[MyLibrary JS (v1.0.0) distribution](MyLibrary-v1.0.0.js)

successComment

The message for the issue comments is generated with Lodash template. The following variables are available:

successComment example

The successComment This ${issue.pull_request ? 'pull request' : 'issue'} is included in version ${nextRelease.version} will generate the comment:

This pull request is included in version 1.0.0

successCommentCondition

A Lodash template string that should evaluate to a truthy or falsy variable. The following variables are available:

successCommentCondition example

• do not create any comments at all: set to false or templating: "<% return false; %>"
• to only comment on issues: "<% return !issue.pull_request; %>"
• to only comment on pull requests: "<% return issue.pull_request; %>"
• to avoid comment on PRs or issues created by Bots: "<% return issue.user.type !== 'Bot'; %>"
• you can use labels to filter issues: "<% return issue.labels?.some((label) => { return label.name === ('semantic-release-relevant'); }); %>"

check the GitHub API issue object for properties which can be used for the filter

failComment

The message for the issue content is generated with Lodash template. The following variables are available:

failComment example

The failComment This release from branch ${branch.name} had failed due to the following errors:\n- ${errors.map(err => err.message).join('\\n- ')} will generate the comment:

This release from branch master had failed due to the following errors:

• Error message 1
• Error message 2

failCommentCondition

A Lodash template string that should evaluate to a truthy or falsy variable. The following variables are available:

failCommentCondition example

• do not create any comments at all: set to false or templating: "<% return false; %>"
• to only comment on main branch: "<% return branch.name === 'main' %>"
• you can use labels to filter issues, i.e. to not comment if the issue is labeled with wip: "<% return !issue.labels?.includes('wip') %>"

check the GitHub API Pull Request Object for properties which can be used for the filter

releasedLabels

Each label name is generated with Lodash template. The following variables are available:

releasedLabels example

The releasedLabels ['released<%= nextRelease.channel ? ` on @\${nextRelease.channel}` : "" %> from <%= branch.name %>'] will generate the label:

released on @next from branch next

addReleases

Add links to other releases to the GitHub release body.

Valid values for this option are false, "top" or "bottom".

addReleases example

See The introducing PR for an example on how it will look.