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
standard-version
Similar to @semantic-release/github, standard-version automates versioning and CHANGELOG generation, but it does so without relying on a continuous integration server. It's more suited for manual releases and doesn't directly integrate with GitHub releases.
release-it
Release-it is a versatile tool for automating versioning and package publishing, similar to @semantic-release/github. It supports various platforms including GitHub, GitLab, and Bitbucket. Unlike @semantic-release/github, it provides a more interactive release process and can be customized for different workflows.
lerna
Lerna is a tool for managing JavaScript projects with multiple packages, making it somewhat similar to @semantic-release/github in terms of release management. It automates the versioning and publishing process for monorepos. While it can work alongside semantic-release for complex workflows, it's primarily focused on monorepo management rather than direct GitHub integration.
@semantic-release/github
Set of semantic-release plugins for publishing a Github release.
verifyConditions
Verify the presence and the validity of the githubToken
(set via option or environment variable).
Options
Option | Description | Default |
---|
githubToken | Required. The token used to authenticate with GitHub. | process.env.GH_TOKEN or process.env.GITHUB_TOKEN |
githubUrl | The GitHub Enterprise endpoint. | process.env.GH_URL or process.env.GITHUB_URL |
githubApiPathPrefix | The GitHub Enterprise API prefix. | process.env.GH_PREFIX or process.env.GITHUB_PREFIX |
publish
Publish a Github release.
Options
Option | Description | Default |
---|
githubToken | Required. The token used to authenticate with GitHub. | process.env.GH_TOKEN or process.env.GITHUB_TOKEN |
githubUrl | The GitHub Enterprise endpoint. | process.env.GH_URL or process.env.GITHUB_URL |
githubApiPathPrefix | The GitHub Enterprise API prefix. | process.env.GH_PREFIX or process.env.GITHUB_PREFIX |
assets | An array of files to upload to the release. | - |
assets option
Each element of the array can be a path to the file or an object
with the properties:
Property | Description | Default |
---|
path | Required. The file path to upload relative to the project directory. | - |
name | The name of the downloadable file on the Github release. | File name extracted from the path . |
label | Short description of the file displayed on the Github release. | - |
Configuration
The plugins are used by default by semantic-release so no specific configuration is requiered if githubToken
, githubUrl
and githubApiPathPrefix
are set via environment variable.
Each individual plugin can be disabled, replaced or used with other plugins in the package.json
:
{
"release": {
"verifyConditions": ["@semantic-release/github", "verify-other-condition"],
"getLastRelease": "custom-get-last-release",
"publish": [
"custom-publish",
{
"path": "@semantic-release/github",
"assets": [
{"path": "dist/asset.min.css", "label": "CSS distribution"},
{"path": "dist/asset.min.js", "label": "JS distribution"}
]
}
]
}
}
The same configuration for Github Enterprise:
{
"release": {
"verifyConditions": [
{
"path": "@semantic-release/github",
"githubUrl": "https://my-ghe.com",
"githubApiPathPrefix": "/api-prefix"
},
"verify-other-condition"
],
"getLastRelease": "custom-get-last-release",
"publish": [
"custom-publish",
{
"path": "@semantic-release/github",
"githubUrl": "https://my-ghe.com",
"githubApiPathPrefix": "/api-prefix",
"assets": [
{"path": "dist/asset.min.css", "label": "CSS distribution"},
{"path": "dist/asset.min.js", "label": "JS distribution"}
]
}
]
}
}