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

\==Publish a Release for the repository==

* [Applicable Events](#git-release-applicable-events)
* [Parameters](#git-release-parameters)
* [Output Results](#git-release-output)
* [Configuration Examples](#git-release-configuration-examples)

## Applicable Events {#git-release-applicable-events}

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

## Parameters {#git-release-parameters}

The list below gives an overview of all `git:release` parameters.

* [overlying](#git-release-parameters-overlying):
  Overlay mode: `true` only edits/updates, `false` deletes then recreates
* [tag](#git-release-parameters-tag): Tag name for the release; not needed on `tag_push`
* [title](#git-release-parameters-title): Release title; defaults to the tag name
* [description](#git-release-parameters-description): Release description
* [descriptionFromFile](#git-release-parameters-descriptionFromFile): Read description content from a local file
* [preRelease](#git-release-parameters-preRelease): Whether to mark the release as a pre-release
* [latest](#git-release-parameters-latest): Whether to set the release as the latest

Detailed descriptions for each parameter are provided below.

::::tip
This built-in task does not support uploading attachments.
You can use the [cnbcool/attachments](https://cnb.cool/cnb/plugins/cnbcool/attachments) task to upload attachments.
::::

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

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

Overlay mode:

* `true`: Overlay mode, meaning this is only for editing or updating the Release.
* `false`: Non-overlay mode, meaning delete first, then recreate the Release.

::::warning
Default is `false`, meaning that when a Release version already exists, it will be deleted first and then recreated.
::::

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

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

Tag name corresponding to the `release`, not required.

For `tag_push` events, this is not needed as it directly takes the Tag name triggering the `tag_push` event.

For non-`tag_push` events, this is required as the Tag name corresponding to the Release.

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

* type: `String` | `Number`
* required: `false`
* default: Tag name

Title of the Release.

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

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

Description of the Release. **When the content is too large,
it is recommended to use the `descriptionFromFile` parameter to pass the content through a file to avoid exceeding
limits.**

::::warning
`description` and `descriptionFromFile` are mutually exclusive and cannot be specified at the same time.
::::

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

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

Read content from a file and use it as the description of the Release.

Specify a local file path, and the system will read the file content and use it as the description of the Release.

::::warning
`description` and `descriptionFromFile` are mutually exclusive and cannot be specified at the same time.
::::

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

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

Whether to set the `release` as a pre-release.

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

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

Whether to set the Release as the latest version.

## Output Results {#git-release-output}

None

## Configuration Examples {#git-release-configuration-examples}

* Generate changelog and automatically update Release description:

```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
```

* Publish a Release when pushing to the main branch:

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