Oceans LLM Docs

Appearance

Release Process ​

See also: Contributing, Deploy and Operations, Admin Runbooks, ADR: Cocogitto Releases, git-cliff Changelogs, and GHCR Image Publishing

This page is the maintainer-facing release runbook.

Source of Truth ​

Release Preflight ​

Before mise run release, confirm:

  • main is up to date locally
  • the intended release state is already merged
  • normal CI is green for that commit
  • generated admin contract artifacts are current
  • changelog-worthy commits are in the expected shape

The tag workflow is distribution, not the quality gate.

Current Release Flow ​

  1. update main locally
  2. run mise run release
  3. review the generated version changes and CHANGELOG.md
  4. confirm the GitHub release was created for the new tag
  5. push the release commit and tag
  6. let the tag-triggered GitHub Actions workflow build, attest, and publish images

What mise run release Does ​

Current task steps:

  1. cog bump --auto --skip-untracked
  2. git-cliff -o CHANGELOG.md
  3. gh release create v$(cog get-version) ...
  4. cargo release version $(cog get-version) --execute

That means release metadata and version updates are authored locally before any push happens. The GitHub release is not created as a draft by this task.

What GitHub Actions Does ​

The pushed v* tag triggers ../.github/workflows/release.yml.

Current workflow responsibilities:

  • build and publish the gateway image
  • build and publish the admin UI image
  • attest image provenance

The workflow does not create or update the GitHub release body. It consumes the pushed tag as the image distribution trigger.

Current Image Reality ​

The workflow is not symmetric across both deployables today:

  • gateway image:
    • linux/amd64
  • admin UI image:
    • linux/amd64
    • linux/arm64

Post-Release Verification ​

After the workflow finishes, verify:

  • the GitHub release exists for the pushed tag
  • the expected image tags were published
  • the release notes look sane
  • the deploy docs still match the image reality

If the release changed admin- or user-visible behavior, update the canonical docs in the same pass.

CI Responsibility Boundary ​

The release workflow does not explicitly depend on prior CI runs.

In practice:

  • maintainers are responsible for cutting releases from a known-good state
  • normal CI is the preflight signal
  • tag CI is the distribution step

Failure Recovery Notes ​

  • If mise run release creates a release but local version changes fail afterward, inspect the working tree before rerunning.
  • If the tag was not pushed, fix the local state and either reuse or delete the created GitHub release deliberately.
  • If the tag was pushed but image publishing failed, fix the workflow issue and rerun the failed workflow for the same tag when possible.
  • Avoid retagging an existing published version unless the release is still private to maintainers and no deploy path consumed it.