Releases

Overview

Cut a release when a commit stops being a commit and becomes a version other people depend on. A release is a title, a set of markdown notes and a set of downloadable files, all attached to a git tag — so whoever consumes your project gets one page saying what changed and one link to download the binary, instead of a 40-character hash and an invitation to build it themselves.

It works for people and for machines in the same way. Anyone who can read the repository can fetch the newest published version from one stable URL that never changes as you ship, and a build can cut the release, attach the artifacts it just produced and publish it in four calls, holding a token that can do nothing else.

Quick start

Before you start

How it works

A release annotates a tag, and the tag outlives it

The tag is the release's identity. There is exactly one release per tag, it is addressed by tag name in every URL, and the tag name cannot be changed afterwards — a release renamed is a release deleted and cut again.

The two live at different layers, which is what makes the following true and occasionally surprising:

• Deleting a release leaves the tag. The tag is a real git ref that clones and checkouts still resolve; the release was the notes and files layered on top of it. Removing the tag as well is a separate deletion in the repository's tag list.
• Deleting or moving the tag does not delete the release. The release keeps its notes and its files, and keeps reporting the commit the tag pointed at when it was cut. Source archives do not follow that snapshot — they are built from the tag as it stands now, so deleting the tag makes them answer 404, and moving it makes them serve the new commit while the release still names the old one.
• Force-moving a tag does not rewrite history on the release. The commit shown on the release is a snapshot taken at the moment you cut it. Cut a new release rather than moving a tag under a published one.

Draft, pre-release and "latest"

Two independent flags decide who sees a release and whether it answers as the newest one:

A draft answers 404 to everyone below Developer, on a public repository as much as a private one, so you can stage release notes in the open without leaking them. Publishing is an edit that clears the draft flag, and it stamps the moment of publication once. Turning a published release back into a draft and publishing it a second time keeps that first stamp, so a version you pull and restore does not jump ahead of everything shipped in between.

The latest-release lookup orders by when a release was published, not by when it was created and not by version order. Publishing a draft you wrote three weeks ago makes it the newest release today. Flag a version as a pre-release when you want it downloadable and listed but never served as the newest — release candidates and nightlies are the reason the flag exists.

The release list orders by a different axis: when each release was created. The two agree as long as you publish in the order you create, and diverge the moment you publish an old draft — it becomes the newest release without moving up the list. So the release the latest lookup serves is not always the one at the top of a page of releases.

Attaching a file is two steps, and the budget is taken at the first

Registering a file reserves its declared size against the namespace budget and hands back a URL signed for 15 minutes and bound to the exact size and content type you declared. The file becomes downloadable only once the upload is confirmed, a moment or two after your PUT returns — until then it is listed on the release with no download link, and downloading it answers 409.

Two consequences worth knowing before you meet them. The reservation is taken against the size you declared, and it is held whether or not you ever upload the bytes — deleting the file (or the whole release) is what gives it back. And because the size is signed into the URL, a PUT whose body is a different length is rejected by storage rather than quietly stored.

Every edit carries the version you last read

A release's version is a concurrency counter, not the version of your software — the software's version is the tag name. Read the release, send that number back with your edit, and an edit that lands on top of somebody else's is refused with 409 instead of silently overwriting their notes. Re-read the release and re-apply your change.

How to

Cut a release from a tag

Give the tag name and, when the tag does not exist, the branch or commit to create it from. The title defaults to the tag name, and the notes are markdown. Create it as a draft when you want to write the notes before anyone sees them; create it published when the version is already out.

If the tag already exists, anything you pass as the target is ignored — the release attaches to the tag exactly where it points. If the tag does not exist and you name no target, the call is refused with 404 rather than inventing one.

When the call does create the tag, it creates the tag first and writes the release second. A refusal at that second step — a release already exists for the name, or the repository is at its release cap — therefore leaves the new tag behind. The tag is harmless and reusable on a retry, so delete it from the repository's tag list only if you do not want it.

Edit the notes, or publish a draft

Editing covers the title, the notes and both flags. Publishing a draft is the same call with the draft flag cleared, and it stamps the moment of publication — which is the moment that decides the latest-release ordering.

Send the version you got when you read the release. Omitting a field leaves it alone rather than clearing it. A release you have just created hands its version back in the create response, so a build that creates a draft and publishes it a moment later needs no extra read in between.

Attach a file to a release

Register the file first — its name, its media type and its exact size in bytes — then send the bytes to the URL you get back. Names are unique within a release, so checksums.txt on v1.4.0 and on v1.5.0 are two different files and neither collides.

An asset name is 1–255 characters of letters, digits, ., _, + and -. Slashes are not allowed, so upload linux-arm64.tar.gz, not dist/linux-arm64.tar.gz. Send the same content type on the PUT that you declared at registration, and let the client set the length from the file — a mismatch of either is refused by storage.

List a repository's releases

Newest-created first, paged. The list carries each release's title, notes, tag and commit, and omits its files: read a single release when you want its download links.

Asking for drafts as somebody below Developer is not an error — the flag is ignored and you get the published slice, which is the same answer you would get without it.

Look up one release by its tag

This is the read that includes the files, so it is the one to use when you want download links rather than a summary.

Point an installer at the newest version

One URL that always resolves to the newest published, non-pre-release version — the thing to put in an install script so it does not need updating every time you ship.

A repository with no published, non-pre-release release answers 404 here, which is the correct answer for a project whose only releases so far are release candidates.

Download an attached file

The download answers with a redirect to a short-lived signed URL, which is what curl -L and a browser both follow without further thought. A single-page web app should not rely on following that redirect: it changes origin, and whether a browser follows it depends on which of the app's request headers survive the hop. Those clients ask for the URL as JSON instead, and navigate to it.

The signed URL it hands out lasts 5 minutes, so mint it at the point of download rather than storing it. A file whose upload has not been confirmed answers 409 rather than handing back an empty download.

Download the source at a release's tag

A .tar.gz or .zip of the repository at the release's tag, built for you — no clone, no history, just the tree. It is addressed through the release, so it exists for tags that have a release and not for bare tags.

Ask for tar.gz or zip; leave the format out and you get tar.gz, and anything other than those two is refused with 400. The format is a query parameter — …/archive?format=zip — not an extension on the path, and the tarball_url and zipball_url a release carries are spelled that way, so following one works without rewriting it. Archives are built once per commit and reused, which makes the second request for a version much faster than the first — and means two tags on the same commit share one archive.

Remove a file from a release

This is also the way to clear a registration whose upload never happened: the file sits at uploading forever, holding its declared bytes against the budget, until you delete it.

Delete a release

Deleting the tag as well is a separate action in the repository's tag list, and it is worth thinking about separately: consumers may have pinned that tag.

Reference

Limits

Three ceilings apply, and all three are enforced before anything is stored.

The release count is per repository and counts drafts. Creating a release at the cap is refused with 429 TOO_MANY_REQUESTS and no release is written — but if the call was also going to create the tag, that tag has already been created and stays. Deleting a release gives the slot straight back.

The file-size ceiling is per file. Registering a file bigger than it is refused with 400 BAD_REQUEST, and the message names the byte limit so a script can report it. A declared size of zero is refused the same way.

The storage budget belongs to the namespace — the top-level group — and is shared with every repository's git objects and every package published to that group's registries. Registering a file that would push the namespace over is refused with 429 TOO_MANY_REQUESTS; the bytes are reserved before the upload URL is issued, so a refusal leaves nothing behind and there is no half-reservation to reclaim. The reservation is held against the size you declared from the moment you register, not from the moment the bytes land, and it is returned when you delete the file or its release.

Two more bounds you can hit while writing rather than while uploading: release notes are capped at 100,000 bytes of markdown — roughly 100,000 characters of plain English, fewer once accents and emoji are involved — and a title at 255 characters. Both are refused with 400 BAD_REQUEST above that. A listing's page size runs from 1 to 100 and is 50 when you leave it out; a value outside the range is clamped to it rather than refused.

Downloads — attached files and source archives alike — are charged against an outbound-transfer budget rather than the storage budget, and an exhausted budget answers 429 TOO_MANY_REQUESTS. The charge is taken before the signed URL is minted, so a refusal means nothing was sent and nothing was billed. Anonymous downloads draw on their own, smaller budget, so signing in raises the ceiling before anything else does.

To raise any of these, an Owner of the top-level group can request a limit increase; every limit in force, and how much of the storage budget is used, is on the group's usage view.

Troubleshooting

Examples

Shipping a version from a build, with GITMOAP_API set to Gitmoap's API base, https://api.gitmoap.com, REPO_ID to the repository's id, and GITMOAP_TOKEN to a token carrying release:create and release:update. It creates the release as a draft, attaches one artifact, then publishes — so nothing is visible until the download is actually there.

The same four steps in the CLI, which resolves the repository from an owner/repo path so a build script does not have to carry an id:

Fetching the newest version from an install script needs no token at all against a public repository. Each file's download path comes back relative to the same API base, so prefix it with $GITMOAP_API to fetch it — and a file whose upload has not been confirmed has no download path at all, which is the check an install script should make before it fetches:

FAQ

Related