rdev/.claude/guides/ops/releasing.md

Releasing rdev-api

When to use: Creating a new versioned release with changelog, container image, and git tag.

Automated Releases (Recommended)

Push to main branch triggers Woodpecker CI to build and deploy automatically:

# Just push - Woodpecker handles the rest
git push origin main

# Or push to both remotes
GITEA_TOKEN=$(kubectl get secret rdev-credentials -n rdev -o jsonpath='{.data.GITEA_TOKEN}' | base64 -d)
git push https://jordan:${GITEA_TOKEN}@git.threesix.ai/jordan/rdev.git main
git push origin main

Images are built via kaniko and pushed to registry.threesix.ai/rdev/*.

Prerequisites (Manual Releases)

• Go installed (for local binary builds if needed)
• KUBECONFIG set: export KUBECONFIG=~/.kube/orchard9-k3sf.yaml
• Access to Gitea (git.threesix.ai/jordan/rdev)

Quick Start

# Release and deploy in one command
./scripts/release.sh v0.8.1 "Fix worker ID config bug" --deploy

# Release only (no deploy)
./scripts/release.sh v0.8.1 "Fix worker ID config bug"

What the Release Script Does

The script (scripts/release.sh) performs these steps in order:

1. Creates changelog - Writes changelog/<version>.md with date and message
2. Updates deployment - Patches deployments/k8s/base/rdev-api.yaml with new image tag
3. Commits and pushes - Commits changelog and deployment changes to main
4. Builds binary - Cross-compiles for linux/amd64 with version embedded
5. Builds container - Creates ghcr.io/orchard9/rdev-api:<version> image
6. Pushes image - Uploads to GitHub Container Registry
7. Tags release - Creates annotated git tag and pushes it

With --deploy flag, it also: 8. Runs migrations - Executes all SQL migrations as rdev superuser 9. Applies manifest - kubectl apply the deployment YAML 10. Restarts deployment - Triggers rollout with new image

Usage

./scripts/release.sh <version> "<changelog message>" [--deploy]

Argument	Description	Example
version	Semver tag (with or without v prefix)	v0.8.1 or 0.8.1
message	Changelog entry describing the release	"Add worker pool support"
--deploy	Also run migrations and deploy to k3s	(optional flag)

Examples

# Full release + deploy (recommended)
./scripts/release.sh v0.9.0 "Add project templates" --deploy

# Bug fix release + deploy
./scripts/release.sh v0.8.2 "Fix nil pointer in command handler" --deploy

# Release only (deploy later manually)
./scripts/release.sh v0.8.3 "Update dependency versions"

Manual Deploy (if not using --deploy)

export KUBECONFIG=~/.kube/orchard9-k3sf.yaml
kubectl apply -f deployments/k8s/base/rdev-api.yaml
kubectl rollout restart -n rdev deployment/rdev-api

Artifacts Created

Artifact	Location
Changelog	changelog/<version>.md
Container images	registry.threesix.ai/rdev/{api,worker,claudebox}:<commit-sha>
Git tag	<version> (annotated)
Updated deployment	deployments/k8s/base/rdev-api.yaml

Image Registry

Images are now stored in Zot (registry.threesix.ai) instead of ghcr.io:

Image	Path
API server	registry.threesix.ai/rdev/api:latest
Worker	registry.threesix.ai/rdev/worker:latest
Claudebox	registry.threesix.ai/rdev/claudebox:latest

Tags: latest and ${CI_COMMIT_SHA:0:8} (8-char commit hash)

Troubleshooting

Docker push fails

Ensure you're authenticated to ghcr.io:

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Build fails

Check Go environment:

go version
go env GOOS GOARCH

Git push rejected

Ensure you have push access and main is up to date:

git pull origin main

Related

• Deploying to k3s
• Credentials Management