cobble/RELEASING.md

Releasing Cobble

Cobble ships as a multi-arch container image and a single install.sh. The repository starts private and is made public at the launch gate below.

Cobble is in alpha (see the note in README.md). Every release published before v1.0.0 is an alpha release: interfaces, the database schema and the settings may change between them, so a release that needs a migration step has to say so in its notes, and Settings > General keeps saying the stage until v1.0.0.

One-time setup

• GITEA_USERNAME and GITEA_TOKEN are set as GitHub Actions secrets. The token needs package write on the Gitea Moduletrace org.
• scripts/publish-gitea.sh can reach Gitea: either GITEA_TOKEN is exported locally, or tea login add has been run for the host (the script then reads the token from ~/.config/tea/config.yml). It needs write:repository on the repository to create the release.
• scripts/publish-github.sh can publish releases: gh auth login has been run, and the token has repo scope.
• The Gitea repository exists at git.tben.me/Moduletrace/cobble and main is pushed to both remotes.
• The GHCR package is made public after the first image push (Settings > Packages > cobble > Change visibility).
• The Gitea package needs nothing: package visibility follows the public Moduletrace org.

Every release

The two publish scripts below do steps 1 to 3, 6 and 10 for you: they run the same checks, tag HEAD with package.json's version, push main and the tag, and create the release object. Everything else is still hand work.

scripts/publish-github.sh publishes to GitHub and, by publishing the release, starts the image build. scripts/publish-gitea.sh publishes the same release to the Gitea mirror. Both accept --version VERSION (defaulting to package.json), --branch, --yes, --dry-run and --skip-checks; run them in that order, since only the GitHub release builds images.

1. bun run typecheck and bun run test pass locally.

2. CI is green on main in GitHub Actions.

3. bash -n install.sh passes.

4. Test the installer on a clean machine, both amd64 and arm64 when possible: - fresh install, signup, one chat reply - rerun with no changes: reports up to date, no restart - update to a new tag: backup taken, data intact - --uninstall keeps data, --uninstall --purge removes it

5. Update the version if the release changes it, including package.json's version (the image reports it on Settings > General when it isn't built from a release tag, and the publish scripts tag with it).

6. Tag and publish a GitHub release:

   scripts/publish-github.sh                 # or: bun run publish:github
   
   # by hand, the script does this:
   git tag -a v0.1.0 -m v0.1.0
   git push origin main
   git push origin refs/tags/v0.1.0
   gh release create v0.1.0 --title v0.1.0 --notes-file notes.md --latest
   

7. The release workflow builds linux/amd64 and linux/arm64 and pushes to ghcr.io/moduletrace/cobble, the registry the installer defaults to. It does not touch Gitea: that registry is on the VPN, and a GitHub runner cannot reach it.

8. Check the manifests:

   docker buildx imagetools inspect ghcr.io/moduletrace/cobble:latest
   

9. Confirm the GHCR package is public and pull it anonymously.

10. Once the build has finished, copy the image into the Gitea registry from the VPN:

    GITEA_TOKEN=... bun run mirror:gitea   # or: scripts/mirror-gitea.sh
    
    It copies the version and commit tags, plus `latest` and
    `major.minor` while this release still owns them, and reads every
    destination digest back. A failure here does not affect the release:
    the installer keeps working from GHCR.
    

11. Publish the release to Gitea as well:

    scripts/publish-gitea.sh                  # or: bun run publish:gitea
    
    # by hand, the script does this:
    git push gitea main
    git push gitea refs/tags/v0.1.0
    

12. Update every install with the one-liner:

    curl -fsSL https://url.moduletrace.com/cobble | sudo bash
    

Launch gate

Before the first public release:

• LICENSE, README.md and RELEASING.md are in place.
• The installer has been tested on a clean amd64 and a clean arm64 host.
• No secrets are tracked (git status, git ls-files, secret scanning).
• The GitHub repository and the Gitea mirror are set to public.
• The GHCR package is public.
• The first release is installed on the real host and a signup, a chat reply, a computer and a routine have been exercised.
• A plain curl | bash install answers on http://<host>:7227, and the same install behind a reverse proxy serves HTTPS, installs the app, gets a live chat socket and can turn on notifications.

Rollback

• Images are tagged with the release version, so an older tag can be installed with --version vX.Y.Z.
• The installer keeps the last five database backups in $COBBLE_HOME/backups. Whole-data archives from Settings > Backups live in $COBBLE_HOME/backups-archives; they are kept, not pruned by the installer.
• Restore a backup from Settings > Backups in the app: a database snapshot, or a whole-data archive (which replaces every folder, the snapshots included, takes a safety archive first and restarts the app). A snapshot can also be restored with the app stopped.