@semantic-release/github

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.

README

@semantic-release/github

Set of Semantic-release plugins for publishing a GitHub release.

verifyConditions

Verify the presence and the validity of the authentication (set via environment variables) and the assets option configuration.

publish

Publish a GitHub release, optionally uploading files.

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.

Environment variables

Variable	Description
GH_TOKEN or GITHUB_TOKEN	Required. The token used to authenticate with GitHub.
GH_URL or GITHUB_URL	The GitHub Enterprise endpoint.
GH_PREFIX or GITHUB_PREFIX	The GitHub Enterprise API prefix.

Options

Option	Description	Default
githubUrl	The GitHub Enterprise endpoint.	GH_URL or GITHUB_URL environment variable.
githubApiPathPrefix	The GitHub Enterprise API prefix.	GH_PREFIX or GITHUB_PREFIX environment variable.
assets	An array of files to upload to the release. See assets.	-

assets

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

Property	Description	Default
path	Required. A glob to identify the files to upload.	-
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.	-

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.

Files can be included even if they have 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.

Usage

The plugins are used by default by Semantic-release so no specific configuration is required if 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", "@semantic-release/npm", "verify-other-condition"],
    "publish": ["@semantic-release/npm", "@semantic-release/github", "other-publish"]
  }
}

Options can be set within the plugin definition in the Semantic-release configuration file:

{
  "release": {
    "verifyConditions": [
      "@semantic-release/npm",
      {
        "path": "@semantic-release/github",
        "githubUrl": "https://my-ghe.com",
        "githubApiPathPrefix": "/api-prefix"
      },
      "verify-other-condition"
    ],
    "publish": [
      "@semantic-release/npm",
      {
        "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"}
        ]
      }
    ]
  }
}