@semantic-release/github

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

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

安装

[!TIP] 如果你正在使用 semantic-release，则无需直接依赖此包。 semantic-release 已经依赖此包，定义你自己的直接依赖可能会在更新 semantic-release 时导致冲突。

$ 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 的说明： 你可以使用在 secret GITHUB_TOKEN 中提供的默认令牌。但是，使用此令牌发布的 release 不会触发 release 事件以启动其他工作流。 如果你有在创建新 release 时触发的 actions，请为此使用生成的令牌，并将其存储在仓库的 secrets 中（任何不同于 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_URL 的 GitHub API 前缀。
GITHUB_API_URL	GitHub API 端点。注意，此项会覆盖 GITHUB_PREFIX。

选项

Option	Description	Default
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	要添加到由该发布版本解决的每个 issue 和 pull request 的评论。设置为 false 以禁用对 issue 和 pull request 的评论。参见 successComment。	:tada: This issue has been resolved in version ${nextRelease.version} :tada:\n\nThe release is available on [GitHub release](<github_release_url>)
successCommentCondition	将此用作条件，决定何时在 issues 或 pull requests 上发表评论。参见 successCommentCondition	-
failComment	当发布失败时创建的 issue 的内容。设置为 false 以禁用发布失败时打开 issue。参见 failComment.	包含指向 semantic-release 文档和支持的链接的友好消息，以及导致发布失败的错误列表。
failTitle	当发布失败时创建的 issue 的标题。设置为 false 以禁用发布失败时打开 issue。	The automated release is failing 🚨
failCommentCondition	将此用作条件，决定在发生失败时何时评论或创建 issues。参见 failCommentCondition.	-
labels	在发布失败时创建的 issue 上要添加的 labels。设置为 false 则不添加任何标签。	['semantic-release']
assignees	在发布失败时创建的 issue 上要添加的 assignees。	-
releasedLabels	在由该发布解决的每个 issue 和 pull request 上要添加的 labels。设置为 false 则不添加任何标签。参见 releasedLabels。	['released<%= nextRelease.channel ? \ on @${nextRelease.channel}` : "" %>']-
addReleases	将向 GitHub Release 添加发布链接。可以是 false、"bottom" 或 "top"。参见 addReleases。	false
draftRelease	一个布尔值，指示是否应创建 GitHub 草稿版本（Draft Release），而不是发布实际的 GitHub 版本。	false
releaseNameTemplate	一个 Lodash 模板，用于自定义 GitHub 版本的名称	<%= nextRelease.name %>
releaseBodyTemplate	一个 Lodash 模板，用于自定义 GitHub 版本的正文	<%= nextRelease.notes %>
discussionCategoryName	用于创建与版本关联的讨论的类别名称。设置为 false 可禁用为版本创建讨论。	false

proxy

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

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

此插件使用 undici's ProxyAgent 提供现代代理支持，并通过 node-https-proxy-agent 和 node-http-proxy-agent 保持向后兼容。这确保了代理功能在企业代理后面的 GitHub Enterprise Server 环境中正常工作。

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。

注意：此插件现在内部使用 undici 的 ProxyAgent 以增强代理支持，尤其适用于位于企业代理后面的 GitHub Enterprise Server 环境。所有现有的代理配置均保持完全兼容。

资源

可以是 glob 或 Array 的 globs 和 Objects，具有以下属性：

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

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"]).

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

每个资产的 name 和 label 是通过 Lodash template 生成的。以下变量可用：

参数	描述
branch	执行发布所用的分支。
lastRelease	上次发布的 Object 中的 version、gitTag 和 gitHead。
nextRelease	当前发布的 Object 中的 version、gitTag、gitHead 和 notes。
commits	具有 hash、subject、body message 和 author 的 Array 提交 Object。

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

资源示例

'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 并以名称 MyLibrary-v1.0.0.js 和标签 MyLibrary JS (v1.0.0) distribution 上传到 GitHub 发布，这将生成链接：

[MyLibrary JS (v1.0.0) distribution](MyLibrary-v1.0.0.js)

successComment

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

参数	描述
branch	包含 Object 以及从执行发布的分支中获取的 name、type、channel、range 和 prerelease 属性。
lastRelease	包含上次发布的 Object、version、channel、gitTag 和 gitHead。
nextRelease	Object 与 version、channel、gitTag、gitHead 和 notes 的发布已完成。
commits	Array 提交 Object 的 hash、subject、body message 和 author。
releases	Array 每次发布时生成一个发布 Object，包含可选的发布数据，例如 name 和 url。
issue	与提交相关的拉取请求使用 GitHub API pull request object，或通过 keywords 解决的 issue 使用 GitHub API issue 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

successCommentCondition

一个 Lodash template 字符串，其求值结果应为真值或假值变量。以下变量可用：

Parameter	Description
branch	Object with name, type, channel, range and prerelease properties of the branch from which the release is done.
lastRelease	Object with version, channel, gitTag and gitHead of the last release.
nextRelease	Object with version, channel, gitTag, gitHead and notes of the release being done.
commits	Array of commit Objects with hash, subject, body message and author.
releases	Array with a release Objects for each release published, with optional release data such as name and url.
issue	A GitHub API Pull Request object for pull requests related to a commit

successCommentCondition 示例

• 不创建任何评论：设置为 false 或模板化："<% return false; %>"
• 仅对 issue 进行评论："<% return !issue.pull_request; %>"
• 仅对 pull request 进行评论："<% return issue.pull_request; %>"
• 避免对由 Bot 创建的 PR 或 issue 进行评论："<% return issue.user.type !== 'Bot'; %>"
• 可以使用 labels 来过滤 issues："<% return issue.labels?.some((label) => { return label.name === ('semantic-release-relevant'); }); %>"

查看 GitHub API issue object 以了解可用于过滤的属性

failComment

issue 内容的消息使用 Lodash template 生成。以下变量可用：

参数	描述
branch	发布失败的分支。
errors	一个 Array 的 SemanticReleaseError。每个错误都具有 message、code、pluginName 和 details 属性。 pluginName 包含抛出错误的插件的包名。 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- ')} 将生成以下评论：

来自分支 master 的发布因以下错误而失败：

• 错误信息 1
• 错误信息 2

failCommentCondition

一个 Lodash 模板 字符串，其求值结果应为真值或假值变量。以下变量可用：

参数	描述
branch	具有 Object、name、type、channel、range 和 prerelease 属性的分支，该分支用于执行发布。
lastRelease	Object with version, channel, gitTag and gitHead of the last release.
nextRelease	Object with version, channel, gitTag, gitHead and notes of the release being done.
commits	Array of commit Objects with hash, subject, body message and author.
releases	Array with a release Objects for each release published, with optional release data such as name and url.
issue	与提交相关的拉取请求的 GitHub API pull request object，或通过 keywords 解决的 issue 的 GitHub API issue object

failCommentCondition 示例

• 完全不创建任何评论：设置为 false 或使用模板："<% return false; %>"
• 仅在 main 分支上评论："<% return branch.name === 'main' %>"
• 可以使用标签来过滤 issues，例如，如果 issue 带有 wip 标签则不评论："<% return !issue.labels?.includes('wip') %>"

请查阅 GitHub API Pull Request Object 以了解可用于过滤的属性

releasedLabels

每个标签名称均通过 Lodash template 生成。以下变量可用：

Parameter	Description
branch	Object with name, type, channel, range and prerelease properties of the branch from which the release is done.
lastRelease	Object with version, channel, gitTag and gitHead of the last release.
nextRelease	Object 与 version、channel、gitTag、gitHead 和 notes 的发布已完成。
commits	Array 提交 Object 与 hash、subject、body message 和 author。
releases	Array 为每个已发布的发布版本生成 Object，包含可选的发布数据，例如 name 和 url。
issue	与提交相关的拉取请求使用 GitHub API pull request object，或通过 keywords 解决的议题使用 GitHub API issue object

releasedLabels 示例

releasedLabels ['released<%= nextRelease.channel ? ` on @\${nextRelease.channel}` : "" %> from <%= branch.name %>'] 将生成标签：

released on @next from branch next

addReleases

在 GitHub 发布正文中添加指向其他发布的链接。

此选项的有效值为 false、"top" 或 "bottom"。

addReleases 示例

参见 The introducing PR 以了解其外观示例。