@semantic-release/github

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

| Step | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 file assets. | | addChannel | Update a GitHub release's pre-release field. | | success | Add a comment to each GitHub Issue or Pull Request resolved by the release and close issues previously open by the fail step. | | fail | Open or update a GitHub Issue with information about the errors that caused the release to fail. |

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

| Variable | Description | | ------------------------------ | ------------------------------------------------------------------- | | GITHUB_TOKEN or GH_TOKEN | Required. The token used to authenticate with GitHub. | | GITHUB_URL or GH_URL | The GitHub server endpoint. | | GITHUB_PREFIX or GH_PREFIX | The GitHub API prefix, relative to GITHUB_URL. | | GITHUB_API_URL | The GitHub API endpoint. Note that this overwrites GITHUB_PREFIX. |

Options

| Option | Description | Default | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | githubUrl | The GitHub server endpoint. | GH_URL or GITHUB_URL environment variable. | | githubApiPathPrefix | The GitHub API prefix, relative to githubUrl. | GH_PREFIX or GITHUB_PREFIX environment variable. | | githubApiUrl | The GitHub API endpoint. Note that this overwrites githubApiPathPrefix. | GITHUB_API_URL environment variable. | | proxy | The proxy to use to access the GitHub API. Set to false to disable usage of proxy. See proxy. | HTTP_PROXY environment variable. | | assets | An array of files to upload to the release. See assets. | - | | successComment | The 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>) | | successCommentCondition | Use this as condition, when to comment on issues or pull requests. See successCommentCondition | - | | failComment | The 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. | | failTitle | The 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 🚨

Github

Install / Use

README