# Releases

Publish a tag with notes and downloadable files from the web app, the CLI or the API, and link to the files from installers and scripts.

## Publish a release

A release is a git tag with a title, Markdown notes and files to download. Push the tag, then publish the release.

```sh
git tag -a v1.4.0 -m "v1.4.0"
git push origin v1.4.0
sailfork release create v1.4.0 dist/app-linux.tar.gz dist/SHA256SUMS --title "App 1.4" --notes-file CHANGELOG.md
```

`release create` saves a draft, uploads each file, then publishes. If an upload fails the release stays a draft, and the error says how to resume.

The CLI does not create the git tag. A published release needs its tag in the repository already. Without it, the command saves the draft and fails to publish, and tells you to push the tag first.

## In the web app

Open **Releases** on a repository. The list shows drafts first for people who can write, then published releases newest first, 30 to a page. Each row shows the title, the tag, who published it and when, the number of files and downloads, and a state word:

| State | Meaning |
| --- | --- |
| **Draft** | Only people who can write to the repository see it. |
| **Pre-release** | Published, but not offered as the latest release. |
| **Latest** | The newest release that is ready for everyone. |

A row also says `tag not pushed yet` for a draft whose tag is not in the repository, and `tag not in the repository` for a published release whose tag was deleted.

Choose **New release** (or **Draft a release** on an empty list). The form has:

- **Tag.** The git tag, like `v1.0.0`. It suggests existing tags. If the tag is not in the repository yet, the form says to push it with `git push origin <tag>`, or to save a draft until you do.
- **Title.** Up to 256 characters. Left empty, the tag is the title.
- **Notes.** Markdown, up to 125,000 characters. You can attach images and files in the text.
- **Files.** Choose **Add files**. Each file can be up to 2 GB. Files upload when you save, with a progress bar.
- **Pre-release.** Publishes the release without making it the latest.

Choose **Publish release** to publish, **Save draft** to keep it hidden, or **Cancel**. On a published release, the button reads **Save changes**. A release's page has **Edit** and **Delete**. Deleting removes the release and its files. The git tag stays.

Only people who can write to the repository publish releases. Everyone else sees published ones, and on a private repository only people who can read it do.

## From the CLI

```sh
sailfork release list
sailfork release view v1.4.0
sailfork release create v1.5.0-rc.1 --prerelease --notes "Release candidate"
sailfork release create v2.0.0 dist/app.zip --draft
sailfork release upload v1.4.0 dist/SHA256SUMS --clobber
sailfork release edit v1.4.0 --draft false
sailfork release delete v1.4.0 --yes
```

| Command | What it does |
| --- | --- |
| `list` | Releases, drafts first when you can write, then newest published first. |
| `view <tag>` | One release with its notes and files. |
| `create <tag> [files...]` | Create a release and upload its files. Flags: `-t`, `--title` (default: the tag), `-n`, `--notes`, `--notes-file <file>` (or `-` for stdin), `--draft` to keep it a draft after the upload, `--prerelease`. |
| `upload <tag> <files...>` | Add files. A draft keeps them hidden until it is published. `--clobber` replaces a file of the same name. |
| `edit <tag>` | Change `--title`, `--notes`, `--notes-file`, `--draft <bool>` and `--prerelease <bool>`. `--draft false` publishes a draft, and `--draft true` turns a published release back into one. Pass at least one. |
| `delete <tag>` | Delete the release and its files. The git tag stays. Takes `--yes` and `--dry-run`. |

Without `-R owner/repo`, the repository comes from the clone's git remote.

## Download links

Each file has a stable address in the shape installers expect:

```sh
curl -fsSLO https://status.sailfork.com/fenil/ocean-landing/releases/download/v1.4.0/app-linux.tar.gz
```

The address answers with a redirect to a download link that works for five minutes, so follow redirects (`-L`). A missing tag or file name answers 404. A draft's files are visible only to people who can write. Every whole download counts once toward the file's download total, and a resumed range or a `HEAD` request does not.

The REST API lists a release's files with their sizes and download counts: see [the REST API](https://status.sailfork.com/docs/api).

## Limits

| Limit | Value |
| --- | --- |
| One file | 2 GB. Larger answers 413 `release assets are at most 2 GB`. |
| Files in one release | 1000. |
| Uploaded to releases by one person | 10 GB in any rolling day. Past it, uploads answer 429. |
| Title | 256 characters. |
| Notes | 125,000 characters. |
| Tag | A valid git tag name, at most 255 bytes: no spaces, no `~ ^ : ? * [ \`, no `..`. |

## Errors

| Message | Cause and fix |
| --- | --- |
| `there is no tag <tag> in this repository; push it first (git push origin <tag>) or save the release as a draft` | You published a release whose tag is not in the repository. Push the tag, or pass `--draft`. |
| `tag <tag> already has a release; edit that one instead` | A tag has one release. Use `release edit`, or delete the release first. |
| `this release already has an asset named <name>; delete it first` | Rename the file, delete the old one, or use `release upload --clobber`. |
| `the file is empty` | Releases do not take empty files. |
| `releases of this repository come from GitHub through the mirror <remote>; change them there` | A repository that follows GitHub as a pull mirror keeps its releases read-only. |
| `no release for tag <tag> in <owner>/<repo>` | `view`, `edit`, `upload` and `delete` name a tag that has no release. `release list` shows what exists. |

## Notes

- Publishing a release does not start CI. `on: release` is accepted in a workflow file, but nothing triggers it. See [CI](https://status.sailfork.com/docs/ci).
- Releases imported from GitHub keep their files and download counts. See [Move from GitHub](https://status.sailfork.com/docs/migrate).
- The `release-rules` API stores who may create `v*` tags, but nothing enforces it yet. See [Branches and protection](https://status.sailfork.com/docs/branches).

## For scripts and agents

The routes are `GET` and `POST /api/repos/{owner}/{repo}/releases`, `GET .../releases/tags/{tag}`, `PATCH` and `DELETE .../releases/{id}`, and `POST .../releases/{id}/assets` with the raw file as the body. Writing needs a token with the `repo:write` scope. See [the REST API](https://status.sailfork.com/docs/api).

---

Every docs page: https://status.sailfork.com/llms.txt
