@semantic-release/github

semantic-release 插件，用于发布 GitHub release 并在已发布的 Pull Requests/Issues 上添加评论。

步骤	描述
`verifyConditions`	验证认证信息（通过环境变量设置）的存在和有效性，以及资产选项配置。
`publish`	发布 GitHub release，可选择上传文件资产。
`addChannel`	更新 GitHub release 的 `pre-release` 字段。
`success`	为每个由该版本解决的 GitHub Issue 或 Pull Request 添加评论，并关闭之前由 `fail` 步骤打开的 issues。
`fail`	打开或更新一个 GitHub Issue，包含导致发布失败的错误信息。

安装

$ npm install @semantic-release/github -D

使用

插件可以在 semantic-release 配置文件中进行配置：

{
  "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" }
        ]
      }
    ]
  ]
}

通过这个例子，GitHub releases 将会发布包含 dist/asset.min.css 和 dist/asset.min.js 文件的版本。

配置

GitHub 认证

GitHub 认证配置是必需的，可以通过环境变量设置。

请参照创建用于命令行的个人访问令牌文档获取认证令牌。该令牌必须通过 GH_TOKEN 环境变量在 CI 环境中可用。与令牌关联的用户必须对仓库具有推送权限。

创建令牌时，最低要求的作用域是：

私有仓库需要 repo
公共仓库需要 public_repo

关于 GitHub Actions 的注意事项： 你可以使用默认提供的 GITHUB_TOKEN 密钥。但是，使用此令牌进行的发布不会触发发布事件来启动其他工作流。如果你有在新创建的发布上触发的操作，请为此生成一个令牌并将其存储在你的仓库的密钥中（任何除 GITHUB_TOKEN 之外的名称都可以）。

当使用 GITHUB_TOKEN 时，最低要求的权限是：

contents: write 用于发布 GitHub release
issues: write 用于在已发布的 issues 上添加评论
pull-requests: write 用于在已发布的 pull requests 上添加评论

环境变量

变量	描述
`GITHUB_TOKEN` 或 `GH_TOKEN`	必需。用于 GitHub 认证的令牌。
`GITHUB_URL` 或 `GH_URL`	GitHub 服务器端点。
`GITHUB_PREFIX` 或 `GH_PREFIX`	GitHub API 前缀，相对于 `GITHUB_URL`。
`GITHUB_API_URL`	GitHub API 端点。注意这会覆盖 `GITHUB_PREFIX`。

选项

选项	描述	默认值
`githubUrl`	GitHub 服务器端点。	`GH_URL` 或 `GITHUB_URL` 环境变量。
`githubApiPathPrefix`	GitHub API 前缀，相对于 `githubUrl`。	`GH_PREFIX` 或 `GITHUB_PREFIX` 环境变量。
`githubApiUrl`	GitHub API 端点。注意，这会覆盖 `githubApiPathPrefix`。	`GITHUB_API_URL` 环境变量。
`proxy`	用于访问 GitHub API 的代理。设置为 `false` 可禁用代理使用。参见 proxy。	`HTTP_PROXY` 环境变量。
`assets`	要上传到发布版本的文件数组。参见 assets。	-
`successComment`	添加到每个由发布版本解决的问题和拉取请求的评论。设置为 `false` 可禁用对问题和拉取请求的评论。参见 successComment。	`:tada: 此问题已在版本 ${nextRelease.version} 中解决 :tada:\n\n发布版本可在 [GitHub release](https://github.com/semantic-release/github/blob/master/<github_release_url>` 上查看
`failComment`	发布失败时创建的问题内容。设置为 `false` 可禁止在发布失败时创建问题。参见 failComment。	友好的消息，包含 semantic-release 文档和支持的链接，以及导致发布失败的错误列表。
`failTitle`	发布失败时创建的问题标题。设置为 `false` 可禁止在发布失败时创建问题。	`自动发布失败 🚨`
`labels`	发布失败时创建的问题要添加的标签。设置为 `false` 可不添加任何标签。	`['semantic-release']`
`assignees`	发布失败时创建的问题要添加的受理人。	-
`releasedLabels`	添加到每个由发布版本解决的问题和拉取请求的标签。设置为 `false` 可不添加任何标签。参见 releasedLabels。	`['released<%= nextRelease.channel ? \` on @${nextRelease.channel}` : "" %>']-`
`addReleases`	是否将发布链接添加到 GitHub Release。可以是 `false`、`"bottom"` 或 `"top"`。参见 addReleases。	`false`
`draftRelease`	一个布尔值，指示是否应创建 GitHub 草稿发布而不是发布实际的 GitHub Release。	`false`
`releaseNameTemplate`	一个 Lodash 模板，用于自定义 GitHub release 的名称	`<%= nextRelease.name %>`
`releaseBodyTemplate`	一个 Lodash 模板，用于自定义 GitHub release 的正文	`<%= nextRelease.notes %>`
`discussionCategoryName`	创建与发布版本相关联的讨论的类别名称。设置为 `false` 可禁用为发布版本创建讨论。	`false`

proxy

可以是 false、代理 URL 或具有以下属性的 Object：

属性	描述	默认值
`host`	必需。要连接的代理主机。	-
`port`	必需。要连接的代理端口。	从 `path` 提取的文件名。
`secureProxy`	如果为 `true`，则使用 TLS 连接到代理。	`false`
`headers`	在 HTTP CONNECT 方法上发送的附加 HTTP 头。	-

有关更多详细信息，请参阅 node-https-proxy-agent 和 node-http-proxy-agent。

proxy 示例

'http://168.63.76.32:3128'：对每个 GitHub API 请求使用运行在主机 168.63.76.32 和端口 3128 上的代理。 {host: '168.63.76.32', port: 3128, headers: {Foo: 'bar'}}：对每个 GitHub API 请求使用运行在主机 168.63.76.32 和端口 3128 上的代理，将 Foo 头的值设置为 bar。

assets

可以是一个 glob 或 glob 和具有以下属性的 Object 的 Array：

属性	描述	默认值
`path`	必需。用于识别要上传文件的 glob。	-
`name`	GitHub release 上可下载文件的名称。	从 `path` 提取的文件名。
`label`	在 GitHub release 上显示的文件简短描述。	-

assets Array 中的每个条目都会单独进行 glob 匹配。glob 可以是一个 String（"dist/**/*.js" 或 "dist/mylib.js"）或一个将一起进行 glob 匹配的 String 数组（["dist/**", "!**/*.css"]）。

如果配置了目录，将包含该目录及其子目录下的所有文件。

每个资产的 name 和 label 使用 Lodash 模板生成。以下变量可用：

参数	描述
`branch`	发布所在的分支。
`lastRelease`	包含上一个发布版本的 `version`、`gitTag` 和 `gitHead` 的 `Object`。
`nextRelease`	包含正在进行的发布版本的 `version`、`gitTag`、`gitHead` 和 `notes` 的 `Object`。
`commits`	包含 `hash`、`subject`、`body`、`message` 和 `author` 的提交 `Object` 数组。

注意：如果一个文件在 assets 中有匹配项，即使它在 .gitignore 中也有匹配项，它也会被包含在内。

assets 示例

'dist/*.js'：包含 dist 目录中的所有 js 文件，但不包括其子目录中的文件。 [['dist', '!**/*.css']]：包含 dist 目录及其子目录中的所有文件，但不包括 css 文件。

[{path: 'dist/MyLibrary.js', label: 'MyLibrary JS distribution'}, {path: 'dist/MyLibrary.css', label: 'MyLibrary CSS distribution'}]：包含 dist/MyLibrary.js 和 dist/MyLibrary.css 文件，并在 GitHub 发布中分别标记为 MyLibrary JS distribution 和 MyLibrary CSS distribution。

[['dist/**/*.{js,css}', '!**/*.min.*'], {path: 'build/MyLibrary.zip', label: 'MyLibrary'}]：包含 dist 目录及其子目录中所有的 js 和 css 文件，但不包括压缩版本，同时包含 build/MyLibrary.zip 文件，并在 GitHub 发布中标记为 MyLibrary。

[{path: 'dist/MyLibrary.js', name: 'MyLibrary-${nextRelease.gitTag}.js', label: 'MyLibrary JS (${nextRelease.gitTag}) distribution'}]：包含 dist/MyLibrary.js 文件，并将其上传到 GitHub 发布中，命名为 MyLibrary-v1.0.0.js，标签为 MyLibrary JS (v1.0.0) distribution，这将生成以下链接：

[MyLibrary JS (v1.0.0) distribution](https://github.com/semantic-release/github/blob/master/MyLibrary-v1.0.0.js

successComment

问题评论的消息使用 Lodash 模板生成。可用以下变量：

参数	描述
`branch`	包含发布所在分支的 `name`、`type`、`channel`、`range` 和 `prerelease` 属性的 `Object`。
`lastRelease`	包含上一次发布的 `version`、`channel`、`gitTag` 和 `gitHead` 的 `Object`。
`nextRelease`	包含当前发布的 `version`、`channel`、`gitTag`、`gitHead` 和 `notes` 的 `Object`。
`commits`	包含提交 `Object` 的 `Array`，每个对象包含 `hash`、`subject`、`body`、`message` 和 `author`。
`releases`	包含每个已发布版本的发布 `Object` 的 `Array`，可能包含可选的发布数据，如 `name` 和 `url`。
`issue`	对于与提交相关的拉取请求，是一个 GitHub API 拉取请求对象；对于通过关键词解决的问题，是一个包含 `number` 属性的 `Object`。

successComment 示例

successComment This ${issue.pull_request ? 'pull request' : 'issue'} is included in version ${nextRelease.version} 将生成以下评论：

This pull request is included in version 1.0.0

failComment

问题内容的消息使用 Lodash 模板生成。可用以下变量：

参数	描述
`branch`	发布失败的分支。
`errors`	SemanticReleaseError 的 `Array`。每个错误都有 `message`、`code`、`pluginName` 和 `details` 属性。<br>`pluginName` 包含抛出错误的插件的包名。<br>`details` 包含以 markdown 格式化的错误信息。

failComment 示例

failComment This release from branch ${branch.name} had failed due to the following errors:\n- ${errors.map(err => err.message).join('\\n- ')} 将生成以下评论：

This release from branch master had failed due to the following errors:

Error message 1

Error message 2

releasedLabels

每个标签名称使用 Lodash 模板生成。可用以下变量：

参数	描述
`branch`	包含发布所在分支的 `name`、`type`、`channel`、`range` 和 `prerelease` 属性的 `Object`。
`lastRelease`	包含上一次发布的 `version`、`channel`、`gitTag` 和 `gitHead` 的 `Object`。
`nextRelease`	包含当前发布的 `version`、`channel`、`gitTag`、`gitHead` 和 `notes` 的 `Object`。
`commits`	包含提交 `Object` 的 `Array`，每个对象包含 `hash`、`subject`、`body`、`message` 和 `author`。
`releases`	包含每个已发布版本的发布 `Object` 的 `Array`，可能包含可选的发布数据，如 `name` 和 `url`。
`issue`	对于与提交相关的拉取请求，是一个 GitHub API 拉取请求对象；对于通过关键词解决的问题，是一个包含 `number` 属性的 `Object`。