Release

AR.IO Node Release

You are driving a multi-phase release process. Each phase ends in a git commit. The narrow tools under tools/ handle file mutations; you handle orchestration, commits, and interpretation.

Phases at a glance

1. Preflight — confirm the repo is ready to start.
2. Prepare — flip version to N, set release date in CHANGELOG, commit.
3. Finalize — wait for image builds, pin image SHAs in docker-compose, commit.
4. Test — bring up each docker compose profile, verify stability.
5. Tag & publish — git tag, push, create GitHub release.
6. Merge to main — merge develop into main through a PR.
7. Post-release — bump to N+1-pre, reset image tags to latest, add new [Unreleased] changelog section, commit.

Work one phase at a time. Stop and confirm with the user before phases with external side effects: tag push, GitHub release creation, merge to main.

Run the release from a dedicated worktree with develop checked out (for example git worktree add ../node-wt-release develop), never from a directory a live gateway runs its compose stack from: Phase 4 runs docker compose down, and the release tools edit docker-compose.yaml. The tools need Node 20 (nvm use); under Node 16 they fail with bad option: --import.

Phase 1 — Preflight

Run: ./tools/release-info --json

Also check:

• git rev-parse --abbrev-ref HEAD — must be develop
• git status --porcelain — must be empty (clean working tree)
• yarn audit — review output. For each high or critical advisory, check whether it is reachable at runtime (trace the dependency path with yarn audit --json) and whether it is new since the last release. Stop for the user only on one that is reachable or new; report the rest.

From release-info output, verify:

• versionIsPre === true (e.g., "53-pre")
• arIoNodeRelease matches version
• changelogUnreleasedHasContent === true
• All RELEASE_MANAGED_IMAGE_VARS (ENVOY, CORE, CLICKHOUSE_AUTO_IMPORT, LITESTREAM) are "latest"
• OBSERVER_IMAGE_TAG is a pinned 40-char SHA (not "latest")

Changelog coverage check

changelogUnreleasedHasContent only confirms the [Unreleased] section is non-empty. Before proceeding, also verify that user-visible changes merged since the last release are actually reflected in that section.

1. Identify the previous release tag (e.g., r75):

   git describe --tags --abbrev=0 --match 'r*'

2. List commits merged to develop since that tag:

   git log --no-merges --pretty='%h %s' r<N-1>..develop

3. Read the [Unreleased] section of CHANGELOG.md and compare. Flag any commit that looks user-visible (feat, fix affecting users, behavior change, new/changed env var, API change, perf) but is not represented by an entry.

Do not flag:

• Commits that fix or revise something also introduced in this release cycle (e.g., a feat: and a follow-up fix: for the same feature within r<N-1>..develop). The net user-visible change is one entry for the feature; intermediate fixes are implementation churn.
• Pure chore:, refactor:, test:, docs:, CI/tooling, or dependency bumps with no user-visible effect.

Report any gaps to the user and pause for them to either add entries or confirm the omission is intentional before continuing.

The release number to use is version.replace('-pre', ''). Confirm with the user before proceeding.

Phase 2 — Prepare

Mutations (run in order):

./tools/changelog-release <N>          # defaults --date to today
./tools/set-version <N>
./tools/set-ar-io-node-release <N>

Summary blurb

changelog-release renames the section heading but does not add a summary paragraph. Immediately under the new ## [Release N] - <date> heading, write a 1-paragraph summary in the style of prior releases (see [Release 74] and [Release 75]): open with "This is a recommended release focused on <2–3 themes>." and then enumerate "Key highlights include…" across the most impactful entries in Added/Changed/Fixed. Verify the paragraph is present before committing.

Commit:

git add CHANGELOG.md src/version.ts docker-compose.yaml
git commit -m "chore: prepare release <N>"
git push origin develop

This push triggers image builds on GitHub Actions. Move on once pushed.

Phase 3 — Finalize

Wait for builds to complete:

gh api repos/ar-io/ar-io-node/actions/runs \
  --jq '.workflow_runs[] | select(.status == "in_progress" or .status == "queued") | .id' \
  | wc -l

When the count is 0, proceed. (Poll at ~2 minute intervals if needed; don't tight-loop.)

Fetch and apply SHAs for each release-managed image:

for image in ar-io-envoy ar-io-core ar-io-clickhouse-auto-import ar-io-litestream; do
  sha=$(gh api "/orgs/ar-io/packages/container/${image}/versions" \
    --jq '.[0].metadata.container.tags[] | select(. != "latest")' | head -1)
  echo "${image}: ${sha}"
  git rev-parse --verify "$sha" || { echo "SHA not in git history!"; exit 1; }
done

The packages API needs the read:packages scope (gh auth refresh -s read:packages). Without it, take each SHA from the image workflow's last successful run on develop. Each workflow tags its image with the commit that triggered the run (github.sha), so that run's head SHA is the newest published tag, and a failed or skipped build cannot yield a SHA with no image:

for wf in build-envoy build-clickhouse-auto-import build-litestream; do
  echo "$wf: $(gh run list --workflow "$wf.yml" --branch develop --status success \
    --limit 1 --json headSha -q '.[0].headSha')"
done

Run history expires. A workflow that has not built for a long time lists no runs (litestream's image dates from 2024). Then keep the previous release's pin, after checking nothing under that workflow's paths: changed since:

git show r<N-1>:docker-compose.yaml | grep 'ar-io-litestream:'
git log --oneline r<N-1>..develop -- litestream/          # must print nothing

The paths each workflow builds on, for that check:

So a ClickHouse schema change moves ar-io-clickhouse-auto-import as well as core.

A newer build that failed leaves the last successful run pointing at an older image, so check that nothing under the workflow's paths changed after the SHA you picked. This must print nothing; if it prints a commit, fix or rerun that build rather than pin the older image:

git log --oneline --first-parent <sha>..develop -- <paths from the table>
``` `ar-io-core` is the commit being released (the head of `develop`, after
any last merges). Whatever the source, confirm every SHA is published before
pinning it:

```bash
docker manifest inspect ghcr.io/ar-io/<image>:<sha> >/dev/null && echo ok

If a change lands on develop after the prepare commit and belongs in the release, merge it, wait for its build, and pin that core image instead; the prepare commit does not need redoing.

Map image name → env var:

Then for each pair:

./tools/set-image-tag <ENV_VAR> <sha>

The observer image stays pinned — do not touch it.

Commit:

git add docker-compose.yaml
git commit -m "chore: finalize release <N> with image SHAs"
git push origin develop

Phase 4 — Test

Ensure Docker is available: docker info >/dev/null.

Test each profile. Between profiles, always run the down-all cleanup:

docker compose --profile clickhouse --profile litestream --profile otel down

Core containers expected to stay running across every profile: envoy, core, redis, observer. Check with:

docker ps --format '{{.Names}}'