Strix/RELEASE.md

Release Process Documentation

This document describes the complete release process for Strix and its Home Assistant add-on.

Overview

Strix consists of two repositories:

• Strix - Main application (Go binary, Docker image)
• hassio-strix - Home Assistant add-on

Both repositories must be released together to maintain version consistency.

Version Files

Strix Repository

File	Line	Purpose
cmd/strix/main.go	23	Application version constant
webui/package.json	3	Frontend version
CHANGELOG.md	Top	Release notes

hassio-strix Repository

File	Line	Purpose
strix/config.json	3	Home Assistant add-on version
strix/CHANGELOG.md	Top	Release notes

Release Workflow

Prerequisites

1. Ensure you're on the develop branch with all changes committed
2. All tests pass: go test ./...
3. Application builds successfully: go build ./...

Step 1: Update Strix Repository

cd /home/user/Strix
git checkout develop

# 1. Update version in code
# Edit cmd/strix/main.go - line 23
#   Version = "1.0.X"

# 2. Update frontend version
# Edit webui/package.json - line 3
#   "version": "1.0.X"

# 3. Update CHANGELOG.md
# Add new section at the top:
#   ## [1.0.X] - YYYY-MM-DD
#   ### Fixed/Added/Changed
#   - Description of changes

# 4. Commit version bump
git add cmd/strix/main.go webui/package.json CHANGELOG.md
git commit -m "Release v1.0.X: Brief description"

# 5. Merge to main
git checkout main
git merge develop --no-ff -m "Merge develop into main for v1.0.X release"

# 6. Create tag
git tag -a v1.0.X -m "Release v1.0.X: Brief description"

# 7. Push everything
git push origin main --tags
git push origin develop

Step 2: Update hassio-strix Repository

cd /home/user/hassio-strix

# 1. Update add-on version
# Edit strix/config.json - line 3
#   "version": "1.0.X"

# 2. Update CHANGELOG
# Edit strix/CHANGELOG.md - add same section as in Strix

# 3. Commit and push
git add strix/config.json strix/CHANGELOG.md
git commit -m "Release v1.0.X: Brief description"
git push origin main

# 4. Create tag
git tag -a v1.0.X -m "Release v1.0.X: Brief description"
git push origin --tags

Step 3: Verify GitHub Actions

After pushing tags, GitHub Actions will automatically:

Strix (eduard256/Strix):

• ✅ release.yml - GoReleaser creates GitHub Release with binaries
• ✅ docker.yml - Builds and pushes Docker images to Docker Hub
  • Tags: 1.0.X, 1.0, 1, latest
  • Platforms: linux/amd64, linux/arm64

hassio-strix (eduard256/hassio-strix):

• ✅ builder.yml - Builds and pushes HA add-on to GHCR
  • Image: ghcr.io/eduard256/hassio-strix-{arch}
  • Architectures: amd64, aarch64

Check status:

# Check Strix actions
gh run list --repo eduard256/Strix --limit 5

# Check hassio-strix actions
gh run list --repo eduard256/hassio-strix --limit 5

Step 4: Verify Release

1. GitHub Release: https://github.com/eduard256/Strix/releases/tag/v1.0.X

   • Should have binaries for all platforms

2. Docker Hub: https://hub.docker.com/r/eduard256/strix/tags

   • Should show new version tag

3. GHCR: https://github.com/eduard256/hassio-strix/pkgs/container/hassio-strix-amd64

   • Should show new version

4. Home Assistant Add-on Store:

   • Users will see update notification automatically

Quick Release Script

For automated release, use this script:

#!/bin/bash
# release.sh - Automated release script

VERSION=$1

if [ -z "$VERSION" ]; then
    echo "Usage: ./release.sh 1.0.X"
    exit 1
fi

echo "🚀 Releasing v$VERSION"

# Strix repo
cd /home/user/Strix
git checkout develop

# Update versions
sed -i "s/Version = \".*\"/Version = \"$VERSION\"/" cmd/strix/main.go
sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" webui/package.json

# Update CHANGELOG (manual step reminder)
echo "⚠️  Please update CHANGELOG.md manually"
read -p "Press enter when done..."

# Commit and merge
git add cmd/strix/main.go webui/package.json CHANGELOG.md
git commit -m "Release v$VERSION"
git checkout main
git merge develop --no-ff -m "Merge develop into main for v$VERSION release"
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin main --tags
git push origin develop

# hassio-strix repo
cd /home/user/hassio-strix

# Update version
sed -i "s/\"version\": \".*\"/\"version\": \"$VERSION\"/" strix/config.json

# Update CHANGELOG (manual step reminder)
echo "⚠️  Please update strix/CHANGELOG.md manually"
read -p "Press enter when done..."

# Commit and tag
git add strix/config.json strix/CHANGELOG.md
git commit -m "Release v$VERSION"
git push origin main
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin --tags

echo "✅ Release v$VERSION complete!"
echo "Check GitHub Actions:"
echo "  - https://github.com/eduard256/Strix/actions"
echo "  - https://github.com/eduard256/hassio-strix/actions"

Troubleshooting

Docker Build Fails

Symptom: "Docker Hub Description" step shows Forbidden error

Cause: Docker Hub Personal Access Token expired or lacks permissions

Solution:

1. Go to Docker Hub → Account Settings → Security → Personal Access Tokens
2. Create new token with Read, Write, Delete scopes
3. Update GitHub secret: https://github.com/eduard256/Strix/settings/secrets/actions
4. Update DOCKER_TOKEN secret

Note: This only affects README updates on Docker Hub. Docker images still build successfully.

Home Assistant Add-on Build Fails

Symptom: Builder workflow fails

Solution:

1. Check strix/Dockerfile for correct Go version
2. Verify strix/build.yaml has correct base images
3. Check logs: gh run view <run-id> --repo eduard256/hassio-strix --log

Version Mismatch

Symptom: Strix shows different version than add-on

Solution:

1. Verify both cmd/strix/main.go and strix/config.json have same version
2. Ensure both repositories have matching tags: git tag -l
3. If needed, delete wrong tag: git tag -d v1.0.X && git push origin :refs/tags/v1.0.X

Release Checklist

Before releasing:

• All changes merged to develop
• Tests pass: go test ./...
• Build succeeds: go build ./...
• CHANGELOG.md updated in both repos
• Version numbers match in all files
• Commit messages don't mention AI/Claude Code

After releasing:

• GitHub Release created with binaries
• Docker images pushed to Docker Hub
• HA add-on images pushed to GHCR
• Home Assistant users can see update

Version Numbering

Strix follows Semantic Versioning:

• MAJOR.MINOR.PATCH (e.g., 1.0.9)
• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

GitHub Actions Overview

Strix Repository

Triggers:

• release.yml: On push tag v*
• docker.yml: On push tag v* or push to main
• ci.yml: On push to any branch

Secrets Required:

• GITHUB_TOKEN (automatic)
• DOCKER_USERNAME
• DOCKER_TOKEN

hassio-strix Repository

Triggers:

• builder.yml: On push tag v* or manual workflow dispatch

Secrets Required:

• GITHUB_TOKEN (automatic)

Notes

• Always release both repositories together
• Keep version numbers synchronized
• Test in Home Assistant Ingress mode before releasing
• Docker/direct mode should work without changes (backward compatibility)