# Publish a release

Publish a release for a tag, with Markdown notes and files to download.

A release names a tag (an existing one, or a new one made at a branch or commit), a title and notes
in Markdown, and can be a pre-release or a draft. Publishing starts workflows with `on: release`.
The examples use the repository id `5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and the tag
v1.4.0.

## Prerequisites

- Permission for `git:CreateRelease`. When the tag does not exist yet, creating it is a push, so
  it also needs `git:PushRepository` and passes the tag protection rules (see
  [Protect tags](protect-tags.md)).
- Uploading or deleting files and publishing a draft need `git:UpdateRelease`; deleting a release
  needs `git:DeleteRelease`.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's releases (without it the
  page is not found).
- The repository is not archived. A release or an upload on an archived repository is refused with
  409 `Repository is archived`.

## Publish it

**Console**
1. In the repository, on the **Code** tab, choose **Releases** in the side panel.
2. Choose **Draft a new release**.
3. For **Tag**, enter v1.4.0.
4. (Optional) For **Target**, enter the branch or commit for a new tag. Left empty, the tag is made
   at the default branch.
5. (Optional) For **Title**, enter a title; the tag is used when it is empty.
6. (Optional) For **Notes**, enter the release notes in Markdown.
7. (Optional) Select **Pre-release** or **Save as draft**.
8. Choose **Publish release** (**Save draft** when **Save as draft** is selected). The release is
   listed with its tag and commit; the newest published release that is not a pre-release carries
   **Latest**.

**CLI**
```sh
dcloud git releases create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --tag-name v1.4.0 --target main --name "1.4.0" --body "Bug fixes"
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/releases
{ "tagName": "v1.4.0", "target": "main", "name": "1.4.0", "body": "Bug fixes" }
```

A tag has at most one release: a second one is refused with 409
`A release for v1.4.0 already exists`. A new tag that a protection rule refuses is refused with
409 and the rule's reason.

A published release fires the `created`, `published` and `released` (or `prereleased`) events. A
draft fires only `created`; publishing it later (`draft: false` with `dcloud git releases update`)
fires `published` and `released` or `prereleased`. The Deutsche Cloud Console has no control for publishing a
draft or deleting a release; use `dcloud git releases update` and `dcloud git releases delete`.

## Upload files

**Upload assets** on a release adds files to download (binaries, archives, checksum lists), up to
2 GiB each (larger is refused with 413 `An asset is limited to 2 GiB`) and 100 per release (the
101st is refused with 409 `A release holds at most 100 assets`). File names are unique within a
release. The upload is a multipart form with the field `file`, so it has no CLI command; use the
Deutsche Cloud Console or the HTTP API:

```sh
curl -X POST "$EWS/git/api/repositories/$REPO_ID/releases/$RELEASE_ID/assets" \
  -H "Authorization: EWS-ACCESS-KEY $KEY" -F "file=@dist/tool-linux-amd64.tar.gz"
```

Anyone who can see the releases (`git:ListReleases`) downloads them. A download is always a plain
file (`application/octet-stream`, as an attachment), and access is checked on every download.
In the release's actions menu, **Manage assets** deletes one; deleting the release deletes its
files with it.

## Result

The release is listed under **Releases** with its notes and files.

## Related

- [Protect tags](protect-tags.md) so only a release pipeline can cut release tags.
- `git.releases.create` · `dcloud git releases create`
