---
url: /zh/build/internal-steps/git/release.md
---
`git:release`

\==仓库发布 Release==

* [适用事件](#git-release-applicable-events)
* [参数](#git-release-parameters)
* [输出结果](#git-release-output)
* [配置样例](#git-release-configuration-examples)

## 适用事件 {#git-release-applicable-events}

* `push`
* `commit.add`
* `branch.create`
* `tag_push`
* `pull_request.merged`
* `api_trigger`
* `web_trigger`
* `tag_deploy`

## 参数 {#git-release-parameters}

以下列表先概览 `git:release` 的全部参数。

* [overlying](#git-release-parameters-overlying)：叠加模式，`true` 时仅编辑/更新，`false` 时先删后建
* [tag](#git-release-parameters-tag)：Release 对应 Tag 名，`tag_push` 事件无需传入
* [title](#git-release-parameters-title)：Release 标题，默认取 Tag 名
* [description](#git-release-parameters-description)：Release 描述
* [descriptionFromFile](#git-release-parameters-descriptionFromFile)：从本地文件读取内容作为描述
* [preRelease](#git-release-parameters-preRelease)：是否设为预发布
* [latest](#git-release-parameters-latest)：是否设为最新版本

各参数详细说明如下。

::::tip
该内置任务不支持上传附件，
可使用 [cnbcool/attachments](https://cnb.cool/cnb/plugins/cnbcool/attachments) 任务上传附件。
::::

### overlying {#git-release-parameters-overlying}

* type: `Boolean`
* required: `false`
* default: `false`

叠加模式

* `true`：叠加模式，即本次仅为编辑或更新 Release。
* `false`：非叠加模式，即先删除，再重新创建 Release。

::::warning
默认为 `false`，即当 Release 版本已经存在时，会先删除这个版本，重新生成。
::::

### tag {#git-release-parameters-tag}

* type: `String` | `Number`
* required: `false`

`release` 对应的 Tag 名，非必填

`tag_push` 事件无需传入，直接取触发 `tag_push` 事件的 Tag 名。

非 `tag_push` 事件必填，用来作为 Release 对应的 Tag 名。

### title {#git-release-parameters-title}

* type: `String` | `Number`
* required: `false`
* default: `tag` 名

Release 的标题

### description {#git-release-parameters-description}

* type: `String`
* required: `false`

Release 的描述。
**当内容过多时，建议使用 `descriptionFromFile` 参数，将内容通过文件传递，避免超出限制。**

::::warning
`description` 和 `descriptionFromFile` 互斥，不能同时指定。
::::

### descriptionFromFile {#git-release-parameters-descriptionFromFile}

* type: `String`
* required: `false`

从文件中读取内容作为 Release 的描述。

指定一个本地文件路径，系统会读取该文件的内容，然后将其作为 Release 的描述。

::::warning
`description` 和 `descriptionFromFile` 互斥，不能同时指定。
::::

### preRelease {#git-release-parameters-preRelease}

* type: `Boolean`
* required: `false`
* default: `false`

是否将 `release` 设置为 预发布

### latest {#git-release-parameters-latest}

* type: "true" | "false" | true | false
* required: `false`
* default: `false`

是否将 Release 设置为最新版本

## 输出结果 {#git-release-output}

无

## 配置样例 {#git-release-configuration-examples}

* 生成 changelog 并自动更新 Release 描述

```yaml title=".cnb.yml"
$:
  tag_push:
    - stages:
        - name: changelog
          image: cnbcool/changelog
          settings:
            latestChangeLogTarget: LATEST_CHANGELOG.md
        - name: upload release
          type: git:release
          options:
            title: release
            descriptionFromFile: LATEST_CHANGELOG.md
```

* 主分支 push 时发布 Release

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: git release
          type: git:release
          options:
            tag: Nightly
            description: description
```