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.
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 withgit 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
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:
curl -fsSLO https://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.
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: releaseis accepted in a workflow file, but nothing triggers it. See CI. - Releases imported from GitHub keep their files and download counts. See Move from GitHub.
- The
release-rulesAPI stores who may createv*tags, but nothing enforces it yet. See Branches and protection.
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.