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. Triggers Woodpecker - Push to Gitea triggers CI build automatically

Note: The release.sh script is a legacy tool. For normal releases, just push to main and let Woodpecker CI handle the build and deploy automatically.

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

Woodpecker build fails

Check pipeline status via API:

WOODPECKER_TOKEN=$(kubectl get secret rdev-credentials -n rdev -o jsonpath='{.data.WOODPECKER_API_TOKEN}' | base64 -d)
curl -H "Authorization: Bearer $WOODPECKER_TOKEN" "https://ci.threesix.ai/api/repos/jordan/rdev/pipelines"

Or view at: https://ci.threesix.ai/jordan/rdev

Zot registry 503 errors

Check Zot pod status:

kubectl get pods -n threesix -l app=zot
kubectl logs -n threesix zot-0 --tail=50

Git push rejected

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

git pull origin main

Related

• Deploying to k3s
• Credentials Management