Publishing Quickstart for Open Source Projects

This is the shortest path from "code and big files on my machine" to "a public release anyone can browse and download, without an account." It is the open-source walkthrough of Publishing Releases - read that for every knob; this page is the ten-minute version.

What you get:

• A public project page at /public/<org-slug>/<project-slug>: rendered README, file browser, previews, release history, contributors, and a download button.
• Downloads that need no account. Visitors browse, preview and stream byte ranges anonymously; each file or source-archive download passes a quick one-time proof-of-work check (a few milliseconds in the browser) that makes bulk scraping expensive. Attached release assets are direct anonymous links. Egress is free and unmetered on every plan.
• Explore and community surfaces: a listing on Explore once a release is ready, optional topics and website on the project's profile, follow-by-email and an Atom feed for new releases, stars from signed-in visitors, and optional public Issues and Discussions.
• A Free plan that needs no card for public projects, with a flat 5 GiB of storage. Private and encrypted projects start on a paid plan. An established open-source project can also apply for a Verified OSS grant (the Pro plan at no cost).

What to expect: Swarmfile is not a full forge (no project boards, milestones or code intelligence), but a public project gets a light issue tracker you can turn on, search inside the latest release's text files, and a fork-to-upstream proposal flow that lands as an ordinary merge request in the upstream project. Git clone and fast-forward push work when the project has git access enabled.

1. Create a public project#

In the web app, New project → Visibility: public. Choose an organization slug and project slug - they become the public URL and the git/LFS path, so pick names you're happy to keep. On a brand-new org, keep the default plaintext tier; a public project must be plaintext (managed encryption is for private work).

No organization yet? Sign up, create one, and stay on the Free plan - public projects are free.

2. Get your files in#

Pick whichever fits your repo:

• From your machine: install the desktop app, mount the project, and copy files onto the drive (Getting Started). Saves stream in the background.

• From an existing git repository: swarmfile git import brings the whole repository in with its history, branches and tags:

  swarmfile git import https://github.com/you/your-project.git
  

  It defaults to a new project named after the repository; --name/--org override, and --into <org>/<project> retries a partial import. Fidelity limits are in Known Limitations.

• Keep your repo where it is and send only the big files: point git-lfs at Swarmfile and keep source on your existing host (Git-LFS):

  git config lfs.url https://hub.swarmfile.com/orgs/<org>/lfs/<project>
  

Whatever the path, use .swarmfile/publicignore.yml to keep private paths out of a release before you tag (see step 4).

3. Tag what you're shipping#

A release always publishes a tag, and a tag names one commit. Commit the state you want (on the drive, via swarmfile commit / swarmfile tag create, or via git push if git access is on), then:

swarmfile tag create v1.0

swarmfile tag never moves an existing tag (a forced git push can). Once a tag is published as a release, treat it as permanent.

4. Publish the release#

The web Releases tab has a publish wizard with a preflight; the CLI is the same thing:

swarmfile release preflight v1.0   # exactly what would publish; exits non-zero if it can't
swarmfile release create v1.0      # publish
swarmfile release list             # pending → ready (or failed, with a reason)

The preflight shows the files and total size, anything .swarmfile/publicignore.yml keeps out, and any tracked paths your ignore files hide from the browser but would still publish. A new release starts pending while the download archive builds, then becomes ready. If a publish failed permanently, tag a new commit and publish that - re-running release create on the same tag does nothing.

5. Attach build artifacts#

Compiled binaries don't belong in the tagged tree. Attach them to the release instead:

swarmfile release attach v1.0 dist/your-tool-1.0-macos-arm64.tar.gz

Or drag them into the release's Assets dialog in the web app. Files over 100 MiB attach with the CLI. Assets are served anonymously on their own rate-limited bucket - unlike release files, they carry no proof-of-work challenge (they're plain download links, which is what package managers and install scripts need) - and the member Releases tab shows a per-asset download count plus a per-path download-activity panel.

6. Polish the public page#

An owner or admin sets what the public page shows from the dashboard's Projects list: the project's menu has Add description (or Edit description) for the description and Edit public profile for topics, website and funding links (more in Public Projects & Org Profiles). The Files tab opens on the release's README, with Issues / Discussions / Releases alongside it, and the org profile at /public/<org-slug> collects your public projects.

7. Keep the door open for contributors#

• Follow / Atom feed: visitors can subscribe to release emails with the Follow releases button (a verified account) or the feed at /public/<org-slug>/<project-slug>/releases.xml.
• git (if enabled in project settings): git clone swarmfile://<org>/<project> gives the full history; fast-forward git push sends commits back. The public page shows the release's commit history too.
• Requests in: a signed-in visitor can request comment or contributor access from the public page; approved contributors upload into the project's Contributions folder, and neither uses a seat (Requesting access).
• Forks: Copy in the project actions copies the release into another org. The copy's public page links back with Forked from.
• Issues and Discussions: turn on Public issues and Public discussions in Project settings → Public page (both off by default). Anyone can read them; posting takes a free account with a verified email. See Issues.
• Contributions back: an owner or admin of a fork picks a branch in project settings' Propose to upstream card and sends it. The branch is copied into the upstream project as a temporary contrib/… branch (a single flattened commit, up to 512 MiB) and reviewed there as an ordinary merge request. The upstream decides, and a proposal never merges itself. The upstream controls who may propose with its Cross-project contributions setting: Off (the default), Proposals (a direct fork's owner or admin may send one), or Open (also a fork of a fork, up to five hops away).
• Funding: add up to five funding links (Open Collective or any https:// link) under the project's menu → Edit public profile in the dashboard's Projects list, and the public page shows a Sponsor button beside Follow.

8. Mirror to GitHub Releases (optional)#

If the project is linked to a GitHub repo (the GitHub App), the repo row's Mirror releases checkbox mirrors each future ready release there - tag, notes and attached assets. It is off by default, one-way (GitHub-side edits are never imported), and unpublishing a release here deletes its mirrored GitHub release. A CI-driven team can instead paste a workflow that calls the project's mirror endpoint on release: published (see Git-LFS → Mirror releases); both routes run the same idempotent mirror, so either can be safely re-run.

9. What's deliberately not built#

Named so you can decide with the real picture: Issues are deliberately light (no boards, milestones, attachments or author edits); content search covers the latest release's text files only, not every branch; git push is fast-forward only, annotated tags and octopus merges are refused, and git access is off by default (turn it on per project); public projects are plaintext. The Known Limitations page keeps the full list.