Releasing EchOS

This document explains how releases work — for the maintainer (you) and for users.

The big picture

EchOS uses git tags to drive releases. When you push a tag like v0.2.0, GitHub Actions takes over and does everything automatically:

you: git tag v0.2.0 && git push origin v0.2.0
         │
         ▼
GitHub Actions (release.yml)
         │
         ├─► Build Docker image for linux/amd64 + linux/arm64
         │        └─► Push to ghcr.io/albinotonnina/echos:0.2.0
         │        └─► Push to ghcr.io/albinotonnina/echos:latest
         │
         ├─► Create GitHub Release
         │        └─► Auto-generated changelog from commits since last tag
         │
         └─► Deploy to your VPS (if deploy secrets are configured)
                  └─► SSH in → docker compose pull → docker compose up -d

You don’t build anything locally. You don’t SSH anywhere. You just tag and push.

How to cut a release (maintainer)

1. Make sure main is in a good state

pnpm typecheck   # no type errors
pnpm test        # all tests pass
pnpm start       # manually verify it works

2. Choose a version number

EchOS uses Semantic Versioning:

Change	Version bump	Example
Bug fixes, small improvements	patch	`v0.1.0` → `v0.1.1`
New features, new plugins	minor	`v0.1.0` → `v0.2.0`
Breaking changes (config schema, API)	major	`v0.1.0` → `v1.0.0`

3. Tag and push

git tag v0.2.0
git push origin v0.2.0

That’s it. Go to the Actions tab on GitHub to watch the pipeline run.

4. Update the Homebrew formula

After pushing the tag, update the tap so brew upgrade echos delivers the new version:

# Get the SHA256 of the new release tarball
curl -sL https://github.com/albinotonnina/echos/archive/refs/tags/v0.X.X.tar.gz | sha256sum

# Update url + sha256 in this repo
# homebrew/echos.rb → url / sha256 lines

# Sync to the tap repo
cp homebrew/echos.rb /path/to/homebrew-echos/Formula/echos.rb
cd /path/to/homebrew-echos
git add Formula/echos.rb && git commit -m "echos v0.X.X" && git push origin main

See homebrew/README.md for the full step-by-step.

5. Check the results

After ~10-15 minutes:

GitHub Release created at https://github.com/albinotonnina/echos/releases with an auto-generated changelog
Docker image available at ghcr.io/albinotonnina/echos:0.2.0 and :latest
Your VPS running the new version (ssh your-server 'cd echos/docker && docker compose ps')

If something goes wrong mid-release

The three jobs (docker, release, deploy) run independently after the image is built. If deploy fails but the image published fine, you can redeploy manually:

# Option A: re-run the failed job from the GitHub Actions UI
# Actions → release.yml → the failed run → Re-run failed jobs

# Option B: force redeploy from your machine
pnpm run deploy

What other users get

When someone else self-hosts EchOS, they don’t need to clone the source or build anything. Their docker-compose.yml just references the pre-built image:

services:
  echos:
    image: ghcr.io/albinotonnina/echos:latest   # ← pulled from GitHub's registry
    ...

When a new version is released, they update by running:

docker compose pull
docker compose up -d

Or, if they installed via install.sh and run it directly with Node:

pnpm update-echos

Pinning to a specific version

Users who don’t want automatic updates can pin to a version tag:

image: ghcr.io/albinotonnina/echos:0.2.0   # won't change until you edit this

What the changelog looks like

GitHub auto-generates the changelog from commits and PR titles since the previous tag. This is why commit message format matters — use Conventional Commits:

feat: add RSS feed plugin
fix: handle undefined cron schedule in wizard
docs: update deployment guide
chore: bump dependencies

A release changelog ends up looking like:

## What's Changed
* feat: add RSS feed plugin by @albinotonnina in #42
* fix: handle undefined cron schedule in wizard by @albinotonnina in #43
* chore: bump dependencies by @dependabot in #44

**Full Changelog**: https://github.com/albinotonnina/echos/compare/v0.1.0...v0.2.0

Deleting a bad tag

If you tagged too early and need to redo it:

# Delete locally
git tag -d v0.2.0

# Delete on GitHub (this will also cancel the running workflow)
git push origin :refs/tags/v0.2.0

# Fix whatever was wrong, then re-tag
git tag v0.2.0
git push origin v0.2.0

Manual deploy (without a release)

If you need to push a fix to your VPS urgently without cutting a release:

# Option A: use the manual deploy workflow
# GitHub → Actions → "Deploy to VPS" → Run workflow

# Option B: use the local deploy script (builds image locally)
pnpm run deploy

Neither of these creates a GitHub Release or publishes a Docker image to ghcr.io.

Getting Started

Architecture

Features

Operations

Releasing

Releasing EchOS

The big picture

How to cut a release (maintainer)

1. Make sure main is in a good state

2. Choose a version number

3. Tag and push

4. Update the Homebrew formula

5. Check the results

If something goes wrong mid-release

What other users get

Pinning to a specific version

What the changelog looks like

Deleting a bad tag

Manual deploy (without a release)

​Releasing EchOS

​The big picture

​How to cut a release (maintainer)

​1. Make sure main is in a good state

​2. Choose a version number

​3. Tag and push

​4. Update the Homebrew formula

​5. Check the results

​If something goes wrong mid-release

​What other users get

​Pinning to a specific version

​What the changelog looks like

​Deleting a bad tag

​Manual deploy (without a release)

Releasing EchOS

The big picture

How to cut a release (maintainer)

1. Make sure main is in a good state

2. Choose a version number

3. Tag and push

4. Update the Homebrew formula

5. Check the results

If something goes wrong mid-release

What other users get

Pinning to a specific version

What the changelog looks like

Deleting a bad tag

Manual deploy (without a release)