feat(ci-cd): auto bump patch version and deploy to staging on merge (#1740)

tyler-dane · claude · web-flow · commit 08f879509402 · 2026-05-12T12:48:37.000-07:00
* feat(ci-cd): auto bump patch version and deploy to staging on merge

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* fix(install): resolve 'latest' to 'main' git ref for file downloads

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* ci: update install.sh with env link

* docs: update self-hosting guides

* docs: add workflow doc

---------

Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/bump-and-tag.yml b/.github/workflows/bump-and-tag.yml
@@ -0,0 +1,33 @@
+name: Bump version and tag
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Bump patch version and push tag
+        run: |
+          LATEST=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+          [ -z "$LATEST" ] && LATEST="v0.0.0"
+          VERSION="${LATEST#v}"
+          MAJOR="${VERSION%%.*}"
+          REST="${VERSION#*.}"
+          MINOR="${REST%%.*}"
+          PATCH="${REST#*.}"
+          NEW_TAG="v${MAJOR}.${MINOR}.$((PATCH + 1))"
+          echo "Bumping ${LATEST} → ${NEW_TAG}"
+          git tag "$NEW_TAG"
+          git push origin "$NEW_TAG"
diff --git a/.github/workflows/publish-images.yml b/.github/workflows/publish-images.yml
@@ -74,3 +74,16 @@ jobs:
             switchbacktech/compass-web:${{ steps.version.outputs.version }}
             switchbacktech/compass-web:${{ steps.version.outputs.minor }}
             switchbacktech/compass-web:latest
+
+  deploy-staging:
+    needs: publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to staging
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.STAGING_SSH_HOST }}
+          username: ${{ secrets.STAGING_SSH_USER }}
+          key: ${{ secrets.STAGING_SSH_KEY }}
+          script: cd ~/compass && ./compass update
diff --git a/docs/CI-CD/README.md b/docs/CI-CD/README.md
diff --git a/docs/CI-CD/workflows.md b/docs/CI-CD/workflows.md
@@ -0,0 +1,76 @@
+# Workflows
+
+Compass uses GitHub Actions for continuous integration, Docker Hub for image distribution, and a VPS for staging.
+
+| Workflow | Trigger | Purpose |
+|---|---|---|
+| Test | Push / PR to `main` | Runs lint, type-check, and unit tests |
+| CodeQL | Push / PR to `main` | Static security analysis |
+| Bump version and tag | Push to `main` | Auto-increments patch version, pushes a new semver tag |
+| Publish Docker images | Push a `v*.*.*` tag | Builds images, pushes to Docker Hub, deploys to staging |
+| Sync docs to compass-docs | Push to `main` touching `docs/**` | Mirrors this `docs/` directory to docs.compasscalendar.com |
+
+---
+
+## Release Flow
+
+Every PR merge to `main` triggers a fully automated chain:
+
+```
+PR merged to main
+  └─► bump-and-tag.yml        — reads latest tag, pushes v1.2.X+1
+        └─► publish-images.yml — builds & pushes images to Docker Hub
+              └─► deploy-staging  — SSHes into VPS, runs ./compass update
+```
+
+**Monthly minor/major releases** remain manual: a maintainer pushes a tag like `v1.3.0` or `v2.0.0`, which skips the bump step and goes straight to publish + deploy.
+
+### Removing a test tag
+
+```sh
+git push origin --delete v1.2.3
+git tag -d v1.2.3
+```
+
+---
+
+## Publish Docker Images
+
+Source: [`.github/workflows/publish-images.yml`](../../.github/workflows/publish-images.yml)
+
+### How it works
+
+1. A semver tag matching `v[0-9]+.[0-9]+.[0-9]+` is pushed (either by `bump-and-tag.yml` or manually).
+2. The workflow strips the `v` prefix and derives two tag aliases:
+   - `1.2.3` — exact patch version
+   - `1.2` — floating minor alias
+3. It builds and pushes three images to [our Docker Hub](https://hub.docker.com/repositories/switchbacktech):
+   - `switchbacktech/compass-backend`
+   - `switchbacktech/compass-mongo`
+   - `switchbacktech/compass-web`
+4. Each image gets all three tags: `1.2.3`, `1.2`, and `latest`.
+5. After all images are pushed, the `deploy-staging` job runs.
+
+### Tag pattern rules
+
+Only clean semver tags trigger the workflow. Tags with suffixes (e.g. `v1.2.3-test`) do not match and are safe to push for local testing without triggering a deploy.
+
+---
+
+## Staging Deploy
+
+Source: `deploy-staging` job in [`.github/workflows/publish-images.yml`](../../.github/workflows/publish-images.yml)
+
+The deploy job SSHes into the staging VPS and runs `./compass update`, which pulls the latest Docker Hub images and restarts the stack.
+
+### Required secrets
+
+All secrets go in **GitHub → Settings → Secrets and variables → Actions**:
+
+| Secret | Value |
+|---|---|
+| `DOCKERHUB_USERNAME` | Docker Hub username for the `switchbacktech` org |
+| `DOCKERHUB_TOKEN` | Docker Hub personal access token (Read & Write) |
+| `STAGING_SSH_HOST` | VPS IP address or hostname |
+| `STAGING_SSH_USER` | Linux user on the VPS that owns `~/compass` |
+| `STAGING_SSH_KEY` | Private key from the deploy keypair (the `compass-staging-deploy` file, not `.pub`) |
diff --git a/docs/self-hosting/backup-and-restore.md b/docs/self-hosting/backup-and-restore.md
@@ -1,4 +1,4 @@
-# Back up and restore your data
+# Back up and Restore
 
 For the Docker install created by `self-host/install.sh` on your server. Backups are manual today. The installer and `./compass update` do not create them for you.
 
diff --git a/docs/self-hosting/google-calendar.md b/docs/self-hosting/google-calendar.md
@@ -1,4 +1,4 @@
-# Add Google Calendar (optional)
+# Add Google Calendar
 
 Google Calendar is optional for self-hosting. Compass works fine with email and password alone. Pick a mode based on what you actually need.
 
diff --git a/docs/self-hosting/server-guide.md b/docs/self-hosting/server-guide.md
@@ -1,4 +1,4 @@
-# Run Compass on a server
+# Setup Compass On A Server
 
 This guide describes the recommended first server setup for one person hosting Compass on a small VPS. One public domain, Compass on `127.0.0.1`, Caddy in front for HTTPS.
 
diff --git a/self-host/install.sh b/self-host/install.sh
@@ -3,6 +3,11 @@
 COMPASS_HOME=${COMPASS_HOME:-$HOME/compass}
 COMPASS_VERSION=${COMPASS_VERSION:-latest}
 COMPASS_RAW_URL=https://raw.githubusercontent.com/SwitchbackTech/compass
+# 'latest' is a Docker Hub tag, not a git ref. Map it to 'main' for raw file downloads.
+case $COMPASS_VERSION in
+  latest) COMPASS_GIT_REF=main ;;
+  *)      COMPASS_GIT_REF=$COMPASS_VERSION ;;
+esac
 
 ENV_FILE=$COMPASS_HOME/.env
 MARKER_FILE=$COMPASS_HOME/.compass-self-host
@@ -428,6 +433,9 @@ write_env_if_missing() {
   umask 077
   TMP_ENV=$COMPASS_HOME/.env.$$
   cat > "$TMP_ENV" <<EOF
+# See for a detailed description of each variable here:
+# https://docs.compasscalendar.com/docs/self-hosting/environment-variables
+
 # Compose
 COMPASS_VERSION=$COMPASS_VERSION
 
@@ -441,9 +449,9 @@ TZ=Etc/UTC
 LOG_LEVEL=info
 
 # Local URLs
-FRONTEND_URL=http://localhost:9080
-BASEURL=http://localhost:3000/api
-CORS=http://localhost:9080,http://localhost:3000
+FRONTEND_URL=https://cal.yourdomain.com
+BASEURL=https://cal.yourdomain.com/api
+CORS=https://cal.yourdomain.com
 
 # Compass MongoDB
 MONGO_INITDB_ROOT_USERNAME=compass
@@ -479,7 +487,7 @@ EOF
 download_compose_file() {
   tmp_compose=$COMPASS_HOME/docker-compose.yml.$$
   info "Downloading docker-compose.yml for Compass ${COMPASS_VERSION}."
-  curl -fsSL "${COMPASS_RAW_URL}/${COMPASS_VERSION}/self-host/docker-compose.yml" -o "$tmp_compose" \
+  curl -fsSL "${COMPASS_RAW_URL}/${COMPASS_GIT_REF}/self-host/docker-compose.yml" -o "$tmp_compose" \
     || fail "Could not download docker-compose.yml for version ${COMPASS_VERSION}. Check that the version exists."
 
   if [ -f "$COMPOSE_FILE" ]; then
@@ -491,7 +499,7 @@ download_compose_file() {
 
 download_helper() {
   info "Downloading compass helper for Compass ${COMPASS_VERSION}."
-  curl -fsSL "${COMPASS_RAW_URL}/${COMPASS_VERSION}/self-host/compass" -o "$HELPER_FILE" \
+  curl -fsSL "${COMPASS_RAW_URL}/${COMPASS_GIT_REF}/self-host/compass" -o "$HELPER_FILE" \
     || fail "Could not download compass helper for version ${COMPASS_VERSION}."
   chmod +x "$HELPER_FILE" || fail "Could not make $HELPER_FILE executable."
 }
@@ -574,7 +582,7 @@ EOF
     $ENV_FILE
   Then rebuild the web image (BASEURL and GOOGLE_CLIENT_ID are baked in at build time):
     $HELPER_FILE rebuild
-  See docs/Self-Hosting/google-calendar.md for setup instructions.
+  See https://docs.compasscalendar.com/docs/self-hosting/google-calendar
 EOF
   else
     cat <<EOF

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Back up and restore your data`
	`1`	`+# Back up and Restore`
`2`	`2`
`3`	`3`	For the Docker install created by `self-host/install.sh` on your server. Backups are manual today. The installer and `./compass update` do not create them for you.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Add Google Calendar (optional)`
	`1`	`+# Add Google Calendar`
`2`	`2`
`3`	`3`	`Google Calendar is optional for self-hosting. Compass works fine with email and password alone. Pick a mode based on what you actually need.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Run Compass on a server`
	`1`	`+# Setup Compass On A Server`
`2`	`2`
`3`	`3`	This guide describes the recommended first server setup for one person hosting Compass on a small VPS. One public domain, Compass on `127.0.0.1`, Caddy in front for HTTPS.
`4`	`4`