Repository files navigation

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

$ npm install @semantic-release/github -D

The plugin can be configured in thesemantic-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 exampleGitHub releases will be published with the filedist/asset.min.css anddist/asset.min.js.

The GitHub authentication configuration isrequired and can be set viaenvironment variables.

Follow theCreating 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 theGH_TOKEN environment variable. The user associated with the token must have push permission to the repository.

When creating the token, theminimum 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 secretGITHUB_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 theGITHUB_TOKEN, theminimum 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

Can befalse, a proxy URL or anObject with the following properties:

Seenode-https-proxy-agent andnode-http-proxy-agent for additional details.

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

Can be aglob or andArray ofglobs andObjects with the following properties:

Each entry in theassetsArray is globbed individually. Aglobcan be aString ("dist/**/*.js" or"dist/mylib.js") or anArray ofStrings that will be globbed together(["dist/**", "!**/*.css"]).

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

Thename andlabel for each assets are generated withLodash template. The following variables are available:

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

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

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

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

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

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

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

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

ThesuccessCommentThis ${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

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

• do not create any comments at all: set tofalse 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 theGitHub API issue object for properties which can be used for the filter

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

ThefailCommentThis 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

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

• do not create any comments at all: set tofalse 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 withwip:"<% return !issue.labels?.includes('wip') %>"

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

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

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

released on @next from branch next

Add links to other releases to the GitHub release body.

Valid values for this option arefalse,"top" or"bottom".

SeeThe introducing PR for an example on how it will look.