Publishing Releases

A release is a tag of a public project, published for anyone to browse and download: a fixed, cached snapshot of exactly what that tag points at. Releases are how you distribute a dataset, a set of sample files, model weights, an asset pack, or a game build from Swarmfile, without anyone needing to join your organization.

This page is the publisher's walkthrough. Public Projects & Org Profiles covers what visitors see and how your organization's public page works.

Before you start#

• The project must be public. Visibility is chosen when a project is created and never changes, and public projects use the unencrypted storage tier (anything the world can download has nothing left to encrypt at rest). On the Free plan every project is public; on a paid plan, choose Public when you create the project. A private project can't be published - copy the content into a new public project instead.
• You need the right access. On a protected-mode project, publishing needs project-wide admin access (org owners and the project's creator always have it). On an open-mode project, any member who can write the whole project can publish. You can't publish a tag that contains anything you're denied read on, and you need a verified email. Permissions has the details, including how a publish fails safe when permissions can't be checked.

1. Tag the commit#

A release always publishes a tag, and a tag always names one commit. Commit the state you want to ship, then tag it:

swarmfile commit -m "Dataset v1.0"
swarmfile tag create v1.0

Tags are immutable pointers: there's no "move this tag." To point a name somewhere else, delete the tag and create it again - but once a tag is published as a release, treat it as permanent, since people may already have downloaded it. Tagging also protects that commit from history clean-up for as long as the tag exists.

2. Publish it#

Publish from the Desktop App's Releases panel, or:

swarmfile release create v1.0
swarmfile release list        # shows pending → ready (or failed)

Publishing from the website dashboard isn't available yet; use the Desktop App or the CLI.

A new release starts pending while Swarmfile builds its download archive, then becomes ready (or failed, with a reason). Re-running release create on a tag that's already published does nothing, unless the earlier attempt failed in a way that can be retried. If a publish failed permanently, tag a new commit and publish that.

To take a release down, swarmfile release delete <id> (the id comes from release list). Unpublishing is a real delete, needs the same access as publishing, and removes the release from your public pages and Explore within a minute or two of edge caching.

What a release includes#

• The whole tagged tree, browsable file by file on the project's public page at /public/<org-slug>/<project-slug>. Anyone can browse, preview, and stream byte ranges of a release's files without an account - a visitor can scrub a large video or dataset before downloading anything.
• Downloads behind a free account. Downloading individual files, or the whole release as a single .tar archive, needs a signed-in (free) Swarmfile account. From the CLI: swarmfile release fetch --org <org> --project <project> --tag v1.0 --out release.tar, or add --path for one file.
• The README the release ships, rendered as the landing view of the project page.
• Generated release notes summarizing what changed since the previous release.
• Download counts per release (they lag by up to about an hour), and the contributors of the release.

Provenance: commit pinning#

A release names the commit hash its tag points at, and the project page shows it with a commit-pinned badge. Because commit hashes chain every file's content and all the history before it, the hash pins exactly what was published. The badge is the pointer, not a proof: anyone can check the project's signed commit chain with swarmfile-verify-history, as Verifiable History explains, and swarmfile materialize hash:<commit-hash> reproduces the exact tree on any machine with access to the project.

Being found: Explore, following, and feeds#

• Explore. Every public project with at least one release is listed on Explore, Swarmfile's public directory, with search over names, descriptions, README text and file paths. There's no separate opt-in: public plus a release means listed. Until the first release, a public project's card shows on your org profile, but there's nothing to browse yet. Archiving a project removes it from the listings until you unarchive it.
• Follow releases. A visitor with a verified free account can follow a project (or your whole organization) and gets one email per new release, with a one-click unsubscribe.
• RSS. Your organization's releases across all its public projects are published as a feed at /feeds/<org-slug>/releases.xml, no account needed.

Getting a copy: fork into your own org#

On a release's public page, Get this project copies that release into a new project in an organization where the visitor can create projects, then offers to open it in the Desktop App. It's a one-time snapshot: the copy doesn't track the original, and later releases don't flow into it. Small releases copy straight away; a large one runs as a background job with progress and a cancel button. The destination organization's plan limits and storage quota apply, and copies are rate-limited per person.

This is also the way to get a public copy of work: publish into a public project, or copy a release into a new project of your own.

What isn't built yet#

• Publishing from the website dashboard (use the Desktop App or CLI).
• A fork that stays linked to its upstream, stars, and public comments.
• Public commit history: visitors see releases, not the project's commit log.
• A public git clone URL. Members of a project with git access turned on can git clone it; anonymous visitors can't.