Socket
Socket
Sign inDemoInstall

@semantic-release/github

Package Overview
Dependencies
390
Maintainers
4
Versions
150
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@semantic-release/github

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


Version published
Maintainers
4
Weekly downloads
1,128,329
decreased by-8.46%

Weekly downloads

Package description

What is @semantic-release/github?

The @semantic-release/github package is designed to automate the release process of your GitHub projects by integrating with semantic versioning. It helps in publishing GitHub releases, managing release notes, and handling assets and pre-releases seamlessly. This package is part of the semantic-release ecosystem, which automates versioning and package publishing.

What are @semantic-release/github's main functionalities?

Publish GitHub Releases

Automatically publish a GitHub release with assets. The configuration allows you to specify which assets to include in the release, such as compiled binaries or distribution packages.

"@semantic-release/github": {
  "assets": [
    {"path": "build/zip/your-package.zip", "label": "Your Package"}
  ]
}

Comment on Released Pull Requests and Issues

Automatically comment on the GitHub issues and pull requests that are part of the release. This feature helps in notifying contributors and users about the resolution of issues and the availability of new versions.

"@semantic-release/github": {
  "successComment": "This issue has been resolved in version \\$VERSION"
}

Add Labels to Pull Requests

Automatically add labels to the pull requests included in the release. This can help in tracking the release status of various changes and organizing pull requests.

"@semantic-release/github": {
  "releasedLabels": ["Status: Released", "\"\\$VERSION\""]
}

Other packages similar to @semantic-release/github

Readme

Source

@semantic-release/github

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

Build Status

npm latest version npm next version npm beta version

StepDescription
verifyConditionsVerify the presence and the validity of the authentication (set via environment variables) and the assets option configuration.
publishPublish a GitHub release, optionally uploading file assets.
addChannelUpdate a GitHub release's pre-release field.
successAdd a comment to each GitHub Issue or Pull Request resolved by the release and close issues previously open by the fail step.
failOpen or update a GitHub Issue with information about the errors that caused the release to fail.

Install

$ 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

VariableDescription
GH_TOKEN or GITHUB_TOKENRequired. The token used to authenticate with GitHub.
GITHUB_API_URL or GH_URL or GITHUB_URLThe GitHub Enterprise endpoint.
GH_PREFIX or GITHUB_PREFIXThe GitHub Enterprise API prefix.

Options

OptionDescriptionDefault
githubUrlThe GitHub Enterprise endpoint.GH_URL or GITHUB_URL environment variable.
githubApiPathPrefixThe GitHub Enterprise API prefix.GH_PREFIX or GITHUB_PREFIX environment variable.
proxyThe proxy to use to access the GitHub API. Set to false to disable usage of proxy. See proxy.HTTP_PROXY environment variable.
assetsAn array of files to upload to the release. See assets.-
successCommentThe comment to add to each issue and pull request resolved by the release. Set to false to disable commenting on issues and pull requests. See successComment.:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)
failCommentThe content of the issue created when a release fails. Set to false to disable opening an issue when a release fails. See failComment.Friendly message with links to semantic-release documentation and support, with the list of errors that caused the release to fail.
failTitleThe title of the issue created when a release fails. Set to false to disable opening an issue when a release fails.The automated release is failing 🚨
labelsThe labels to add to the issue created when a release fails. Set to false to not add any label.['semantic-release']
assigneesThe assignees to add to the issue created when a release fails.-
releasedLabelsThe labels to add to each issue and pull request resolved by the release. Set to false to not add any label. See releasedLabels.['released<%= nextRelease.channel ? \ on @${nextRelease.channel}` : "" %>']-
addReleasesWill add release links to the GitHub Release. Can be false, "bottom" or "top". See addReleases.false
draftReleaseA boolean indicating if a GitHub Draft Release should be created instead of publishing an actual GitHub Release.false
releaseNameTemplateA Lodash template to customize the github release's name<%= nextverison.name %>
releaseBodyTemplateA Lodash template to customize the github release's body<%= nextverison.notes %>
discussionCategoryNameThe category name in which to create a linked discussion to the release. Set to false to disable creating discussion for a release.false
proxy

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

PropertyDescriptionDefault
hostRequired. Proxy host to connect to.-
portRequired. Proxy port to connect to.File name extracted from the path.
secureProxyIf true, then use TLS to connect to the proxy.false
headersAdditional HTTP headers to be sent on the HTTP CONNECT method.-

See node-https-proxy-agent and node-http-proxy-agent for additional details.

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.

assets

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

PropertyDescriptionDefault
pathRequired. A glob to identify the files to upload.-
nameThe name of the downloadable file on the GitHub release.File name extracted from the path.
labelShort description of the file displayed on the GitHub release.-

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:

ParameterDescription
branchThe branch from which the release is done.
lastReleaseObject with version, gitTag and gitHead of the last release.
nextReleaseObject with version, gitTag, gitHead and notes of the release being done.
commitsArray of commit Objects with hash, subject, body message and author.

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:

ParameterDescription
branchObject with name, type, channel, range and prerelease properties of the branch from which the release is done.
lastReleaseObject with version, channel, gitTag and gitHead of the last release.
nextReleaseObject with version, channel, gitTag, gitHead and notes of the release being done.
commitsArray of commit Objects with hash, subject, body message and author.
releasesArray with a release Objects for each release published, with optional release data such as name and url.
issueA GitHub API pull request object for pull requests related to a commit, or an Object with the number property for issues resolved via keywords
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

failComment

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

ParameterDescription
branchThe branch from which the release had failed.
errorsAn Array of SemanticReleaseError. Each error has the message, code, pluginName and details properties.
pluginName contains the package name of the plugin that threw the error.
details contains a information about the error formatted in markdown.
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
releasedLabels

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

ParameterDescription
branchObject with name, type, channel, range and prerelease properties of the branch from which the release is done.
lastReleaseObject with version, channel, gitTag and gitHead of the last release.
nextReleaseObject with version, channel, gitTag, gitHead and notes of the release being done.
commitsArray of commit Objects with hash, subject, body message and author.
releasesArray with a release Objects for each release published, with optional release data such as name and url.
issueA GitHub API pull request object for pull requests related to a commit, or an Object with the number property for issues resolved via keywords
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.

Keywords

FAQs

Last updated on 15 Mar 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc