| 1 | # @semantic-release/github
|
| 2 |
|
| 3 | [**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to publish a
|
| 4 | [GitHub release](https://help.github.com/articles/about-releases) and comment on released Pull Requests/Issues.
|
| 5 |
|
| 6 | [](https://github.com/semantic-release/github/actions?query=workflow%3ATest+branch%3Amaster)
|
| 7 |
|
| 8 | [](https://www.npmjs.com/package/@semantic-release/github)
|
| 9 | [](https://www.npmjs.com/package/@semantic-release/github)
|
| 10 | [](https://www.npmjs.com/package/@semantic-release/github)
|
| 11 |
|
| 12 | | Step | Description |
|
| 13 | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 14 | | `verifyConditions` | Verify the presence and the validity of the authentication (set via [environment variables](#environment-variables)) and the [assets](#assets) option configuration. |
|
| 15 | | `publish` | Publish a [GitHub release](https://help.github.com/articles/about-releases), optionally uploading file assets. |
|
| 16 | | `addChannel` | Update a [GitHub release](https://help.github.com/articles/about-releases)'s `pre-release` field. |
|
| 17 | | `success` | Add a comment to each [GitHub Issue](https://help.github.com/articles/about-issues) or [Pull Request](https://help.github.com/articles/about-pull-requests) resolved by the release and close issues previously open by the `fail` step. |
|
| 18 | | `fail` | Open or update a [GitHub Issue](https://help.github.com/articles/about-issues) with information about the errors that caused the release to fail. |
|
| 19 |
|
| 20 | ## Install
|
| 21 |
|
| 22 | ```bash
|
| 23 | $ npm install @semantic-release/github -D
|
| 24 | ```
|
| 25 |
|
| 26 | ## Usage
|
| 27 |
|
| 28 | The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):
|
| 29 |
|
| 30 | ```json
|
| 31 | {
|
| 32 | "plugins": [
|
| 33 | "@semantic-release/commit-analyzer",
|
| 34 | "@semantic-release/release-notes-generator",
|
| 35 | [
|
| 36 | "@semantic-release/github",
|
| 37 | {
|
| 38 | "assets": [
|
| 39 | { "path": "dist/asset.min.css", "label": "CSS distribution" },
|
| 40 | { "path": "dist/asset.min.js", "label": "JS distribution" }
|
| 41 | ]
|
| 42 | }
|
| 43 | ]
|
| 44 | ]
|
| 45 | }
|
| 46 | ```
|
| 47 |
|
| 48 | With this example [GitHub releases](https://help.github.com/articles/about-releases) will be published with the file `dist/asset.min.css` and `dist/asset.min.js`.
|
| 49 |
|
| 50 | ## Configuration
|
| 51 |
|
| 52 | ### GitHub authentication
|
| 53 |
|
| 54 | The GitHub authentication configuration is **required** and can be set via [environment variables](#environment-variables).
|
| 55 |
|
| 56 | Follow the [Creating a personal access token for the command line](https://help.github.com/articles/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.
|
| 57 |
|
| 58 | When creating the token, the **minimum required scopes** are:
|
| 59 |
|
| 60 | - [`repo`](https://github.com/settings/tokens/new?scopes=repo) for a private repository
|
| 61 | - [`public_repo`](https://github.com/settings/tokens/new?scopes=public_repo) for a public repository
|
| 62 |
|
| 63 | _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.
|
| 64 | 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).
|
| 65 |
|
| 66 | When using the _GITHUB_TOKEN_, the **minimum required permissions** are:
|
| 67 |
|
| 68 | - `contents: write` to be able to publish a GitHub release
|
| 69 | - `issues: write` to be able to comment on released issues
|
| 70 | - `pull-requests: write` to be able to comment on released pull requests
|
| 71 |
|
| 72 | ### Environment variables
|
| 73 |
|
| 74 | | Variable | Description |
|
| 75 | | -------------------------------------------- | --------------------------------------------------------- |
|
| 76 | | `GH_TOKEN` or `GITHUB_TOKEN` | **Required.** The token used to authenticate with GitHub. |
|
| 77 | | `GITHUB_API_URL` or `GH_URL` or `GITHUB_URL` | The GitHub Enterprise endpoint. |
|
| 78 | | `GH_PREFIX` or `GITHUB_PREFIX` | The GitHub Enterprise API prefix. |
|
| 79 |
|
| 80 | ### Options
|
| 81 |
|
| 82 | | Option | Description | Default |
|
| 83 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 84 | | `githubUrl` | The GitHub Enterprise endpoint. | `GH_URL` or `GITHUB_URL` environment variable. |
|
| 85 | | `githubApiPathPrefix` | The GitHub Enterprise API prefix. | `GH_PREFIX` or `GITHUB_PREFIX` environment variable. |
|
| 86 | | `proxy` | The proxy to use to access the GitHub API. Set to `false` to disable usage of proxy. See [proxy](#proxy). | `HTTP_PROXY` environment variable. |
|
| 87 | | `assets` | An array of files to upload to the release. See [assets](#assets). | - |
|
| 88 | | `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](#successcomment). | `:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)` |
|
| 89 | | `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](#failcomment). | Friendly message with links to **semantic-release** documentation and support, with the list of errors that caused the release to fail. |
|
| 90 | | `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 🚨` |
|
| 91 | | `labels` | The [labels](https://help.github.com/articles/about-labels) to add to the issue created when a release fails. Set to `false` to not add any label. | `['semantic-release']` |
|
| 92 | | `assignees` | The [assignees](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users) to add to the issue created when a release fails. | - |
|
| 93 | | `releasedLabels` | The [labels](https://help.github.com/articles/about-labels) to add to each issue and pull request resolved by the release. Set to `false` to not add any label. See [releasedLabels](#releasedlabels). | `['released<%= nextRelease.channel ? \` on @\${nextRelease.channel}\` : "" %>']- |
|
| 94 | | `addReleases` | Will add release links to the GitHub Release. Can be `false`, `"bottom"` or `"top"`. See [addReleases](#addReleases). | `false` |
|
| 95 | | `draftRelease` | A boolean indicating if a GitHub Draft Release should be created instead of publishing an actual GitHub Release. | `false` |
|
| 96 | | `releaseNameTemplate` | A [Lodash template](https://lodash.com/docs#template) to customize the github release's name | `<%= nextverison.name %>` |
|
| 97 | | `releaseBodyTemplate` | A [Lodash template](https://lodash.com/docs#template) to customize the github release's body | `<%= nextverison.notes %>` |
|
| 98 | | `discussionCategoryName` | The category name in which to create a linked discussion to the release. Set to `false` to disable creating discussion for a release. | `false` |
|
| 99 |
|
| 100 | #### proxy
|
| 101 |
|
| 102 | Can be `false`, a proxy URL or an `Object` with the following properties:
|
| 103 |
|
| 104 | | Property | Description | Default |
|
| 105 | | ------------- | -------------------------------------------------------------- | ------------------------------------ |
|
| 106 | | `host` | **Required.** Proxy host to connect to. | - |
|
| 107 | | `port` | **Required.** Proxy port to connect to. | File name extracted from the `path`. |
|
| 108 | | `secureProxy` | If `true`, then use TLS to connect to the proxy. | `false` |
|
| 109 | | `headers` | Additional HTTP headers to be sent on the HTTP CONNECT method. | - |
|
| 110 |
|
| 111 | See [node-https-proxy-agent](https://github.com/TooTallNate/node-https-proxy-agent#new-httpsproxyagentobject-options) and [node-http-proxy-agent](https://github.com/TooTallNate/node-http-proxy-agent) for additional details.
|
| 112 |
|
| 113 | ##### proxy examples
|
| 114 |
|
| 115 | `'http://168.63.76.32:3128'`: use the proxy running on host `168.63.76.32` and port `3128` for each GitHub API request.
|
| 116 | `{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`.
|
| 117 |
|
| 118 | #### assets
|
| 119 |
|
| 120 | Can be a [glob](https://github.com/isaacs/node-glob#glob-primer) or and `Array` of
|
| 121 | [globs](https://github.com/isaacs/node-glob#glob-primer) and `Object`s with the following properties:
|
| 122 |
|
| 123 | | Property | Description | Default |
|
| 124 | | -------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------ |
|
| 125 | | `path` | **Required.** A [glob](https://github.com/isaacs/node-glob#glob-primer) to identify the files to upload. | - |
|
| 126 | | `name` | The name of the downloadable file on the GitHub release. | File name extracted from the `path`. |
|
| 127 | | `label` | Short description of the file displayed on the GitHub release. | - |
|
| 128 |
|
| 129 | Each entry in the `assets` `Array` is globbed individually. A [glob](https://github.com/isaacs/node-glob#glob-primer)
|
| 130 | can be a `String` (`"dist/**/*.js"` or `"dist/mylib.js"`) or an `Array` of `String`s that will be globbed together
|
| 131 | (`["dist/**", "!**/*.css"]`).
|
| 132 |
|
| 133 | If a directory is configured, all the files under this directory and its children will be included.
|
| 134 |
|
| 135 | The `name` and `label` for each assets are generated with [Lodash template](https://lodash.com/docs#template). The following variables are available:
|
| 136 |
|
| 137 | | Parameter | Description |
|
| 138 | | ------------- | ----------------------------------------------------------------------------------- |
|
| 139 | | `branch` | The branch from which the release is done. |
|
| 140 | | `lastRelease` | `Object` with `version`, `gitTag` and `gitHead` of the last release. |
|
| 141 | | `nextRelease` | `Object` with `version`, `gitTag`, `gitHead` and `notes` of the release being done. |
|
| 142 | | `commits` | `Array` of commit `Object`s with `hash`, `subject`, `body` `message` and `author`. |
|
| 143 |
|
| 144 | **Note**: If a file has a match in `assets` it will be included even if it also has a match in `.gitignore`.
|
| 145 |
|
| 146 | ##### assets examples
|
| 147 |
|
| 148 | `'dist/*.js'`: include all the `js` files in the `dist` directory, but not in its sub-directories.
|
| 149 |
|
| 150 | `[['dist', '!**/*.css']]`: include all the files in the `dist` directory and its sub-directories excluding the `css`
|
| 151 | files.
|
| 152 |
|
| 153 | `[{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.
|
| 154 |
|
| 155 | `[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]`: include all the `js` and
|
| 156 | `css` files in the `dist` directory and its sub-directories excluding the minified version, plus the
|
| 157 | `build/MyLibrary.zip` file and label it `MyLibrary` in the GitHub release.
|
| 158 |
|
| 159 | `[{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:
|
| 160 |
|
| 161 | > `[MyLibrary JS (v1.0.0) distribution](MyLibrary-v1.0.0.js)`
|
| 162 |
|
| 163 | #### successComment
|
| 164 |
|
| 165 | The message for the issue comments is generated with [Lodash template](https://lodash.com/docs#template). The following variables are available:
|
| 166 |
|
| 167 | | Parameter | Description |
|
| 168 | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 169 | | `branch` | `Object` with `name`, `type`, `channel`, `range` and `prerelease` properties of the branch from which the release is done. |
|
| 170 | | `lastRelease` | `Object` with `version`, `channel`, `gitTag` and `gitHead` of the last release. |
|
| 171 | | `nextRelease` | `Object` with `version`, `channel`, `gitTag`, `gitHead` and `notes` of the release being done. |
|
| 172 | | `commits` | `Array` of commit `Object`s with `hash`, `subject`, `body` `message` and `author`. |
|
| 173 | | `releases` | `Array` with a release `Object`s for each release published, with optional release data such as `name` and `url`. |
|
| 174 | | `issue` | A [GitHub API pull request object](https://developer.github.com/v3/search/#search-issues) for pull requests related to a commit, or an `Object` with the `number` property for issues resolved via [keywords](https://help.github.com/articles/closing-issues-using-keywords) |
|
| 175 |
|
| 176 | ##### successComment example
|
| 177 |
|
| 178 | The `successComment` `This ${issue.pull_request ? 'pull request' : 'issue'} is included in version ${nextRelease.version}` will generate the comment:
|
| 179 |
|
| 180 | > This pull request is included in version 1.0.0
|
| 181 |
|
| 182 | #### failComment
|
| 183 |
|
| 184 | The message for the issue content is generated with [Lodash template](https://lodash.com/docs#template). The following variables are available:
|
| 185 |
|
| 186 | | Parameter | Description |
|
| 187 | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 188 | | `branch` | The branch from which the release had failed. |
|
| 189 | | `errors` | An `Array` of [SemanticReleaseError](https://github.com/semantic-release/error). Each error has the `message`, `code`, `pluginName` and `details` properties.<br>`pluginName` contains the package name of the plugin that threw the error.<br>`details` contains a information about the error formatted in markdown. |
|
| 190 |
|
| 191 | ##### failComment example
|
| 192 |
|
| 193 | 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:
|
| 194 |
|
| 195 | > This release from branch master had failed due to the following errors:
|
| 196 | >
|
| 197 | > - Error message 1
|
| 198 | > - Error message 2
|
| 199 |
|
| 200 | #### releasedLabels
|
| 201 |
|
| 202 | Each label name is generated with [Lodash template](https://lodash.com/docs#template). The following variables are available:
|
| 203 |
|
| 204 | | Parameter | Description |
|
| 205 | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| 206 | | `branch` | `Object` with `name`, `type`, `channel`, `range` and `prerelease` properties of the branch from which the release is done. |
|
| 207 | | `lastRelease` | `Object` with `version`, `channel`, `gitTag` and `gitHead` of the last release. |
|
| 208 | | `nextRelease` | `Object` with `version`, `channel`, `gitTag`, `gitHead` and `notes` of the release being done. |
|
| 209 | | `commits` | `Array` of commit `Object`s with `hash`, `subject`, `body` `message` and `author`. |
|
| 210 | | `releases` | `Array` with a release `Object`s for each release published, with optional release data such as `name` and `url`. |
|
| 211 | | `issue` | A [GitHub API pull request object](https://developer.github.com/v3/search/#search-issues) for pull requests related to a commit, or an `Object` with the `number` property for issues resolved via [keywords](https://help.github.com/articles/closing-issues-using-keywords) |
|
| 212 |
|
| 213 | ##### releasedLabels example
|
| 214 |
|
| 215 | The `releasedLabels` ``['released<%= nextRelease.channel ? ` on @\${nextRelease.channel}` : "" %> from <%= branch.name %>']`` will generate the label:
|
| 216 |
|
| 217 | > released on @next from branch next
|
| 218 |
|
| 219 | #### addReleases
|
| 220 |
|
| 221 | Add links to other releases to the GitHub release body.
|
| 222 |
|
| 223 | Valid values for this option are `false`, `"top"` or `"bottom"`.
|
| 224 |
|
| 225 | ##### addReleases example
|
| 226 |
|
| 227 | See [The introducing PR](https://github.com/semantic-release/github/pull/282) for an example on how it will look.
|