writeonce/docs/guides/releasing.md

# Cutting a release — building the tarball and publishing it on GitHub

The `/install` page on writeonce.de links a GitHub release asset by an
exact URL. Publishing is therefore not "upload a file somewhere": the
**asset filename has to match what the site links**, or the download
button 404s. This runbook keeps the two in step.

The URL the site links today:

```
https://github.com/shoneyj/writeonce/releases/download/v0.1.0/writeonce-0.1.0-linux-amd64.tar.gz
```

which decomposes as `<repo>/releases/download/<tag>/<asset-name>`. So the
tag must be `v0.1.0` and the asset must be named exactly
`writeonce-0.1.0-linux-amd64.tar.gz` — which is what `just dist` already
produces.

## Two routes

**Automated (preferred).** `.github/workflows/release.yml` builds,
verifies and publishes on a `v*` tag push. It needs no `gh auth login`
and no secret: GitHub injects a per-job `GITHUB_TOKEN`, and the single
line `permissions: contents: write` is what lets that token create a
release. The token expires when the job ends, so there is nothing to
rotate or leak. Skip to *Releasing from the pipeline* below.

**Manual.** Everything from §0 onward — the path for a first release, or
when the pipeline is broken and you need to ship anyway.

## Making the pipeline ready (first time only)

It does **not** build on your machine, and pushing to `master` does not
release anything. The job runs on a GitHub-hosted runner, and only a
`v*` TAG push starts it. Ordinary commits, PRs and branch pushes are
ignored by this workflow.

```
 1  Get the workflow onto GitHub — Actions only sees files in the repo.
      git checkout master
      git merge site-homepage          # or open a PR and merge it
      git push origin master

 2  Repo -> Actions tab. If it offers to enable workflows, enable them.

 3  Repo -> Settings -> Actions -> General -> "Allow actions":
      must permit actions/checkout and ocaml/setup-ocaml.
      On "Allow select actions", add:  ocaml/setup-ocaml@*

 4  Same page -> "Workflow permissions". The workflow asks for
    contents: write explicitly, which is normally enough. If the
    publish step later fails with 403, come back and select
    "Read and write permissions".

 5  REHEARSE with a dry run — no tag, no publish, no cleanup.
    Actions tab -> "release" -> "Run workflow" -> master.
    A workflow_dispatch run skips the tag guard and the publish step,
    so it builds, verifies, smoke-tests the extracted tarball and
    reports the glibc floor, and stops there.

 6  (nothing to undo — a dry run creates no tag and no release)

 7  Watch it: the Actions tab, or `gh run watch` once gh is
    authenticated.

 8  Read the "Report the glibc floor" step. It prints what the
    RUNNER-built binaries actually require. Expect 2.35-ish from
    ubuntu-22.04, versus 2.38 from this dev machine.

 9  Update docs/examples/site/install/view.wo's supported-systems list
    to whatever step 8 printed, and the distros that follow from it.
    Publishing binaries whose floor differs from the page is the one
    failure a user cannot debug.

10  Clean up the rehearsal:
      gh release delete v0.0.0-test --yes
      git push origin :refs/tags/v0.0.0-test
      git tag -d v0.0.0-test

11  Remove --draft, commit, push.

12  Ship for real:
      git tag -a v0.1.0 -m "writeonce 0.1.0"
      git push origin v0.1.0

13  Verify the link a stranger clicks (should print 200):
      curl -sIL -o /dev/null -w '%{http_code}\n' \
        https://github.com/shoneyj/writeonce/releases/download/v0.1.0/writeonce-0.1.0-linux-amd64.tar.gz

14  Refresh the site's mirror from $WO_DIST (section 7 below).
```

Known first-run risks, in the order they are likely to bite:
`ocaml/setup-ocaml@v3` resolving OCaml 4.14 on the 22.04 image; the
`objdump` in the glibc-floor step needing `binutils` (present on GitHub
runners, absent in slim containers); and a 403 on publish, which is
step 4.

## What the hosted runner costs

**Public repository: nothing.** Standard GitHub-hosted runners are free
with unlimited minutes on public repos. Only *larger* runners (4-core
and up) are billed there, and this workflow does not ask for one.

**Private repository:** each plan includes monthly minutes — 2,000 on
Free, 3,000 on Pro and Team, 50,000 on Enterprise Cloud — then bills
per minute. Linux counts ×1, Windows ×2, macOS ×10, so staying on Linux
is also the cheap choice. Each *job* is rounded up to the next minute.

This job is small either way. A cold `scripts/mkdist.sh` measured 3.4s
on a 20-core workstation; on a 2-core runner call it well under a
minute. The real cost is `ocaml/setup-ocaml`, which is minutes cold and
under one when its opam cache hits — so budget roughly 3–10 minutes per
release, and it only ever runs on a tag. Ten releases a month is a
couple of percent of the smallest free allowance.

Release assets do **not** count against Actions artifact storage; they
live with the release. (Rates and allowances change — check the current
billing page before making a decision that depends on them.)

## Why the release job is NOT on a self-hosted runner

A self-hosted runner would work — it needs no inbound ports, polls
GitHub over outbound HTTPS, and honours `HTTPS_PROXY`/`NO_PROXY`, so a
box behind a proxy is fine. Two reasons not to use one for THIS job:

**It defeats the point of pinning the runner.** The release binaries
link glibc dynamically, so the build host sets the floor every user
must clear. `ubuntu-22.04` was chosen to keep that floor near 2.35. A
runner on a developer machine (glibc 2.39 here) puts it back at 2.38+
and silently drops Ubuntu 22.04, Debian 12 and RHEL 9 — the exact
regression the pinned image prevents. If a self-hosted runner is
unavoidable, build inside a container pinned to the oldest glibc you
intend to support, not on the host.

**A release built on a workstation is unattested.** "It built on my
machine" is what a pipeline exists to stop being true.

### If you do self-host, what you are accepting

A runner executes workflow code **as the user that started it**, with
that user's filesystem and network reach. On a personal workstation
that means `~/.ssh`, `~/.config/gh`, cloud and cluster credentials,
browser profiles, and every host reachable from it — including LAN
services and anything named in `~/.ssh/config`, which on a work laptop
is usually production. A job does not need to be malicious to leak;
it needs to be careless once.

The risk is highest on a **public** repository, where a pull request
from a stranger can run arbitrary code on the runner. GitHub's own
guidance is not to use self-hosted runners with public repositories.
On a private repository the blast radius is smaller but not zero:
anyone with write access, or one compromised token, reaches the same
shell.

If it is still the right call, make it boring:

- a dedicated VM or container, never a workstation, on a network
  segment that cannot reach production;
- a separate unprivileged user with no SSH keys, no cloud config, and
  no credentials of its own;
- `--ephemeral` registration so each job gets a clean runner and a
  poisoned toolchain cannot outlive one build;
- `.credentials` under the runner's home is a long-lived credential to
  act as that runner — treat the box as holding a secret;
- restrict egress if the workload allows; the same outbound HTTPS the
  runner needs is what exfiltration would use.

A reasonable split: self-hosted for tests that need private-network
access or unusual hardware, GitHub-hosted for the release artifact.

## Releasing from the pipeline

```
git tag -a v0.1.0 -m "writeonce 0.1.0"
git push origin v0.1.0
```

That is the whole release. The workflow then, in order: checks the tag
matches `VERSION`, builds via `scripts/mkdist.sh`, asserts the produced
filename is the one `/install` links, verifies the `.sha256`, extracts
the tarball and builds a hello project **with the binaries inside it**,
prints the glibc floor of what is about to ship, and publishes both
files with `gh release create`.

Two things about that file are deliberate:

- **`runs-on: ubuntu-22.04`, not `ubuntu-latest`.** The binaries link
  glibc dynamically, so the build host's glibc caps the symbol versions
  they can import — and that cap becomes the minimum glibc every user
  needs. On 24.04 (glibc 2.39) the floor is 2.39; on 22.04 (2.35) it is
  2.35. That is the difference between excluding and including Ubuntu
  22.04, Debian 12 and RHEL 9. Changing the image changes who can run
  the release, so change `install/view.wo`'s supported-systems list in
  the same commit.
- **It fails rather than publishes** when the tag, `VERSION` and the
  asset name disagree, because those three are what the download URL on
  `/install` is built from.

### Other CI (GitLab, Jenkins, Buildkite)

No `gh auth login` there either — `gh` reads a token from the
environment:

```
GH_TOKEN=$MY_SECRET gh release create v0.1.0 dist/*.tar.gz dist/*.sha256
```

The secret is a PAT with `repo` scope (classic) or **Contents: read and
write** (fine-grained). Outside GitHub it is a long-lived credential you
own and must rotate — which is exactly the cost `GITHUB_TOKEN` avoids,
and the reason to prefer Actions for this one job even if the rest of
your CI lives elsewhere.

## 0. Authenticate `gh` (manual route only)

`gh` keeps its own credential, separate from git's. SSH keys let you
`git push`; they do **not** let `gh` call the API, so a machine that
pushes fine can still fail to create a release.

Check first — if this names your account, skip the rest of this section:

```
gh auth status
```

### The interactive flow (what to pick)

```
gh auth login
```

It asks five things:

| prompt | answer |
| --- | --- |
| What account do you want to log into? | **GitHub.com** |
| Preferred protocol for Git operations? | **SSH** — this repo's remote is already `git@github.com:shoneyJ/writeonce.git`, and answering HTTPS here rewrites how git talks to GitHub for every repo on the host |
| Upload your SSH public key? | pick `~/.ssh/id_ed25519.pub`, or **Skip** if that key is already on your account |
| How would you like to authenticate? | **Login with a web browser** |
| One-time code | gh prints something like `ABCD-1234`; press Enter, paste it at <https://github.com/login/device>, authorise |

The token lands in the system credential store, or in a plain file if
there is no store (`gh auth status` prints the location; `--insecure-storage`
forces the file). `-w`/`--web` skips straight to the browser step.

**In a Claude Code session, prefix it with `!`** — `! gh auth login` — so
the prompts are yours to answer and the output lands in the conversation.
An agent cannot complete a device flow on your behalf.

### No browser on that machine (server, container, CI)

Create a personal access token at <https://github.com/settings/tokens>.
Classic tokens need the scopes `repo`, `read:org` and `gist`;
a fine-grained token needs **Contents: read and write** on the repo,
which is what release assets are written through. Then:

```
printf '%s' "$TOKEN" | gh auth login --with-token
```

Read it from a `chmod 600` file rather than typing it inline — an
argument on the command line lands in shell history and in `ps`. For
automation, skip login entirely and export `GH_TOKEN`; gh picks it up and
stores nothing.

### Verify before you rely on it

```
gh auth status
gh repo view shoneyJ/writeonce --json name,visibility
```

The second call is the real check: it proves the token can reach *this*
repo, which a valid-but-wrong-account token would not.

## 1. Before you build

Check the tree is clean and the version is what you mean to ship —
`VERSION` is the single source, and `mkdist.sh` refuses to build if
`woc version` or `wovm --version` disagree with it:

```
git status --porcelain     # expect empty
cat VERSION                # e.g. 0.1.0
```

## 2. Build the artifact

```
just dist
```

That builds both release binaries, runs the version drift guard, and
writes two files:

```
dist/writeonce-<ver>-linux-amd64.tar.gz
dist/writeonce-<ver>-linux-amd64.tar.gz.sha256
```

## 3. Verify it before anyone else can

Two checks, both cheap, both worth it. First the digest:

```
cd dist && sha256sum -c writeonce-0.1.0-linux-amd64.tar.gz.sha256 && cd ..
```

Then prove the tarball actually works, using the binaries INSIDE it —
not the ones in your build tree:

```
tmp=$(mktemp -d)
tar -C "$tmp" -xzf dist/writeonce-0.1.0-linux-amd64.tar.gz
export PATH="$tmp/writeonce/bin:$PATH"
woc version && wovm --version

mkdir -p "$tmp/hello" && cd "$tmp/hello"
printf 'name    = "hello"\nversion = "0.1.0"\n\n[runtime]\nwo = ">= 0.1"\n' > wo.toml
printf 'fn main() -> Int {\n  print("hello, writeonce");\n  return 0;\n}\n' > main.wo
woc . && ./target/hello
```

If that prints `hello, writeonce`, the release is sound.

## 4. Tag the commit

The tag is what the download URL points at, so tag the exact commit the
binaries were built from:

```
git tag -a v0.1.0 -m "writeonce 0.1.0"
git push origin v0.1.0
```

## 5. Publish and upload

One command creates the release and attaches both files:

```
gh release create v0.1.0 \
  dist/writeonce-0.1.0-linux-amd64.tar.gz \
  dist/writeonce-0.1.0-linux-amd64.tar.gz.sha256 \
  --title "writeonce 0.1.0" \
  --notes-file - <<'EOF'
Linux x86-64, glibc 2.38 or newer. Two binaries — `woc` and `wovm` —
depending only on the system C library.

    rm -rf /usr/local/writeonce
    tar -C /usr/local -xzf writeonce-0.1.0-linux-amd64.tar.gz
    export PATH=$PATH:/usr/local/writeonce/bin

Verify with the published `.sha256` before extracting.
EOF
```

Add `--draft` to stage it without publishing, or `--prerelease` to mark
it as one. If the release already exists and you only need to attach (or
replace) files:

```
gh release upload v0.1.0 dist/writeonce-0.1.0-linux-amd64.tar.gz --clobber
```

Without `gh`, the same thing through the web UI: the repo's **Releases**
page → *Draft a new release* → choose tag `v0.1.0` → drag both files
into the attachment box → *Publish release*. Uploading by hand is where
the filename usually drifts, so paste it rather than retyping it.

## 6. Check the link the site actually uses

```
curl -sIL -o /dev/null -w '%{http_code} %{url_effective}\n' \
  https://github.com/shoneyj/writeonce/releases/download/v0.1.0/writeonce-0.1.0-linux-amd64.tar.gz
```

A `200` means `/install`'s download button works for a stranger. Anything
else means the tag, the asset name, or the repo path disagrees with the
link in `docs/examples/site/install/view.wo`.

## 7. Refresh the site's mirror

`/install` offers this site as a mirror beside the GitHub link, served by
the framework's `StaticFiles` out of `$WO_DIST` (default `./dist`). Copy
the same two files there so the mirror is not stale:

```
scp dist/writeonce-0.1.0-linux-amd64.tar.gz* user@host:/srv/writeonce/dist/
```

Both copies are the same bytes, and the published `.sha256` covers
either one — that is the point of shipping the digest beside the
archive.

## Notes

- **`dist/` is gitignored** (`.gitignore:103`). The tarball is a build
  artifact; the release is where it lives, not the repository.
- **Repo path case.** The git remote is `shoneyJ/writeonce` while the
  site links `shoneyj/writeonce`. GitHub paths are case-insensitive and
  redirect, so both resolve — but keep them consistent when either
  changes.
- **Bumping the version** means editing `VERSION`, rebuilding, and
  updating every place the site names the current release:
  `docs/examples/site/install/view.wo` (the download links, the tar
  command, and the `.sha256` link). The version appears there as literal
  text, so grep for the old number before you publish.
- **One target today.** `mkdist.sh` builds `linux-amd64` only; a cross
  matrix is future work. Do not add architectures to the release notes
  that no build produces.