Releases

https://<host>/repos/<owner>/<repo>/archive/<ref>.zip
https://<host>/repos/<owner>/<repo>/archive/<ref>.tar.gz

curl -LO https://<host>/repos/<owner>/<repo>/releases/assets/<asset-id>/app-release.apk

BASE=https://<host>/api/v1/repos/<owner>/<repo>/releases

# create the release (cuts the tag from main if it does not exist yet)
curl -sS -X POST "$BASE" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"tag_name":"v1.0.0","target_commitish":"main","name":"1.0.0"}'

# attach the build output
curl -sS -X POST "$BASE/tags/v1.0.0/assets" -H "Authorization: Bearer $TOKEN" \
  -F attachment=@build/app-release.apk

# and later, fetch it back by name
curl -sSLO "$BASE/tags/v1.0.0/assets/app-release.apk"

# Releases

A **release** turns a git tag into something people can read and download: a
title, Markdown release notes, source-code archives of exactly that tag, and any
**prebuilt files you attach** — an APK, a JAR, an installer, a checksum list.
Every repository has a **Releases** section in its left sidebar, next to Tags.

The archives are generated from the tag, so they always match the source. The
attached files are the ones that *cannot* be derived from it: the artifacts you
built.

Releases annotate tags — they never change history. Deleting a release keeps the
tag it was published from.

## Who can do what

| Action | Who |
|---|---|
| Browse releases, read notes, download archives and attached files | Anyone who can read the repository |
| Publish, edit, delete a release; attach and delete files | The repository owner, its collaborators, and organisation members |

A private repository's releases (and its archives) are invisible to everyone
without read access — the pages answer `404`, not `403`.

## Publishing a release

1. Open **Releases → New release**.
2. **Tag** — type the tag name, e.g. `v1.0.0`. The field suggests tags that
   already exist and have no release yet.
3. **Create the tag from** — pick a branch when the tag does not exist yet.
   git-shark then creates an annotated tag on that branch's current commit as
   part of publishing. When the tag already exists, this choice is ignored.
4. **Title** — optional; defaults to the tag name.
5. **Release notes** — optional Markdown (headings, lists, tables, links).
   Embedded raw HTML is escaped, so notes can never inject markup into the page.
6. **This is a pre-release** — tick for a release candidate or beta.

Publishing takes you straight to the new release page.

## The release page

- The **Latest** badge marks the newest release that is *not* a pre-release.
  Pre-releases are listed normally but never become "latest".
- **Source code (zip)** and **Source code (tar.gz)** download the repository tree
  at that tag. Both unpack into a single `<repo>-<tag>/` directory.
- Attached files are listed above the archives, each with its size and how often
  it has been downloaded.
- The commit link opens the exact revision the tag pointed at when the release
  was published.
- Owners and collaborators get **Edit** and **Delete** buttons, an **Attach a
  prebuilt file** form, and a **✕** next to each attached file.

Editing changes the title, the notes and the pre-release flag. The tag and its
commit stay fixed — publish a new release to ship a new version.

## Attaching a prebuilt file

Use **Attach a prebuilt file** on the release page. One file per upload; repeat
for as many as you need.

File names must be made up of letters, digits, and `.` `_` `-` `+` `~`, must
start with a letter or digit, and cannot contain spaces or directories — so
`app-release.apk`, `gitshark-1.0.0.jar` and `SHA256SUMS.txt` are all fine,
`my app.apk` is not. Rename before uploading. Two files in the same release
cannot share a name.

Your admin sets the maximum upload size (200 MB unless they changed it). A larger
file is rejected.

Deleting a file is permanent — re-upload to restore one. Deleting the release
deletes everything attached to it, but never the git tag.

## Downloading without the UI

The archive URLs work for any ref, not just released tags:

```
https://<host>/repos/<owner>/<repo>/archive/<ref>.zip
https://<host>/repos/<owner>/<repo>/archive/<ref>.tar.gz
```

`<ref>` may be a tag, a branch, or a commit id. For a private repository, the
usual login (browser session) is required.

Attached files have stable links too, shown on the release page:

```bash
curl -LO https://<host>/repos/<owner>/<repo>/releases/assets/<asset-id>/app-release.apk
```

## Publishing from CI

A build pipeline can attach its artifact with a [personal access
token](profile.md) — no browser needed:

```bash
BASE=https://<host>/api/v1/repos/<owner>/<repo>/releases

# create the release (cuts the tag from main if it does not exist yet)
curl -sS -X POST "$BASE" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"tag_name":"v1.0.0","target_commitish":"main","name":"1.0.0"}'

# attach the build output
curl -sS -X POST "$BASE/tags/v1.0.0/assets" -H "Authorization: Bearer $TOKEN" \
  -F attachment=@build/app-release.apk

# and later, fetch it back by name
curl -sSLO "$BASE/tags/v1.0.0/assets/app-release.apk"
```

## Limits today

- **One file per upload.** There is no multi-file picker; attach them one by one.
- **No checksums are computed.** Upload your own `SHA256SUMS` file if you want
  people to verify downloads.
- **No drafts.** A published release is immediately visible to everyone who can
  read the repository.
- Releases are not announced to federation followers.

Related: [Comments](comments.md) · [Repository visibility](repository-visibility.md)