Release System

Tenki Cloud uses a custom release system designed for polyglot monorepos, handling both TypeScript/Node.js applications and Go binaries seamlessly.

Overview

The release system automates version management, changelog generation, and artifact building across all components in the monorepo. It provides a developer-friendly workflow similar to Changesets but with full support for Go modules and Docker deployments.

Key Features

• Polyglot Support: Handles both Node.js packages and Go binaries
• Shared Go Versioning: All Go binaries use coordinated versions
• Deployment Awareness: Different strategies for Docker vs binary deployment
• Automatic PR Management: Creates and updates Release PRs
• GitHub Integration: Native releases with artifact uploads
• Developer-Friendly CLI: Interactive changelog creation

Quick Start

Creating a Release

1. Create a changelog:

   changelog add          # Interactive with fzf (if available)
   changelog add --empty  # Empty changelog for internal changes
   

2. Commit and push:

   git add .releases/your-changelog.md
   git commit -m "feat: add new feature"
   git push origin main
   

3. Review the Release PR that gets created automatically

4. Merge the Release PR to trigger the release

Checking Status

changelog status

Components

The release system manages these components:

Frontend Applications

• @tenki/app → Docker image: app:vX.Y.Z
• @tenki/sentinel → Docker image: sentinel:vX.Y.Z

Go Services (Docker)

• @tenki/engine → Docker image: engine:vX.Y.Z
• @tenki/github-proxy → Docker image: github-proxy:vX.Y.Z

Go Binaries (Direct Deployment)

• @tenki/cli → Binary releases: tenki-cli-vX.Y.Z-{os}-{arch}
• @tenki/node-agent → Binary releases: node-agent-vX.Y.Z-{os}-{arch}
• @tenki/vm-agent → Binary releases: vm-agent-vX.Y.Z-{os}-{arch}

Changelog Format

Changelog files use YAML frontmatter to specify affected packages and version bump types:

---
"@tenki/app": minor
"@tenki/engine": patch
"@tenki/cli": major
---

Add new authentication features

- **Frontend**: Added MFA support with TOTP
- **Engine**: Fixed token refresh race condition
- **CLI**: Breaking change: new login command structure

This release improves security and fixes several authentication issues.

Version Bump Types

• patch (0.0.X): Bug fixes, small improvements
• minor (0.X.0): New features, backwards compatible
• major (X.0.0): Breaking changes

Go Binary Versioning

All Go binaries share the same version from backend/go.mod. When any Go binary is updated, all Go binaries receive the same version bump using the highest bump type among them.

Example: If @tenki/cli needs a patch and @tenki/engine needs a minor, all Go binaries get a minor bump.

Workflow

1. Changelog Detection

• Trigger: .releases/*.md files pushed to main
• Action: Parses changelog files, determines version bumps
• Result: Creates or updates Release PR

2. Release PR

• Contains: Version bumps for all affected components
• Updates: Individual CHANGELOG.md files
• Shows: Artifacts that will be built
• Cleanup: Deletes temporary changelog files

3. Release Automation

• Trigger: Release PR merged to main
• Actions:
  • Creates Git tags
  • Builds Docker images
  • Builds cross-platform binaries
  • Creates GitHub release with artifacts

CLI Commands

Interactive Changelog Creation

changelog add

Guides you through:

1. Selecting affected packages
2. Choosing version bump types
3. Writing changelog content

Status Check

changelog status

Shows:

• Pending changelog files
• Existing Release PRs
• Current component versions

File Structure

.releases/
├── config.json              # Release configuration
└── *.md                     # Temporary changelog files

# Individual changelogs
apps/app/CHANGELOG.md
apps/sentinel/CHANGELOG.md
backend/cmd/engine/CHANGELOG.md
backend/cmd/tenki-cli/CHANGELOG.md
backend/cmd/node-agent/CHANGELOG.md
backend/cmd/github-proxy/CHANGELOG.md
backend/cmd/vm-agent/CHANGELOG.md

GitHub Actions

Changelog Detection

File: .github/workflows/changelog-detection.yml

• Trigger: Push to main with .releases/*.md changes
• Action: Processes changelogs and creates Release PR

Release Automation

File: .github/workflows/release.yml

• Trigger: Release PR merged to main
• Actions: Creates tags, builds artifacts, publishes releases

Configuration

The system is configured in .releases/config.json:

{
  "packages": {
    "@tenki/app": {
      "path": "apps/app",
      "type": "node",
      "changelog": "apps/app/CHANGELOG.md",
      "version_file": "apps/app/package.json",
      "deployment": "docker"
    },
    "@tenki/engine": {
      "path": "backend/cmd/engine",
      "type": "go-binary",
      "changelog": "backend/cmd/engine/CHANGELOG.md",
      "version_file": "backend/cmd/engine/VERSION",
      "binary_name": "engine",
      "deployment": "docker",
      "docker": {
        "component": "engine",
        "dockerfile": "backend/cmd/engine/Dockerfile",
        "context": "backend"
      }
    }
  },
  "release_branch": "release/next",
  "release_pr_title": "chore(release): version packages [skip ci]",
  "commit_message": "chore(release): version packages [skip ci]"
}

Best Practices

Changelog Writing

• One changelog per logical change - Don’t combine unrelated features
• Clear descriptions - Explain what changed and why
• User-focused content - Write for end users, not developers
• Appropriate bump types - Follow semantic versioning strictly

Release Management

• Review Release PRs carefully - Verify versions and changelog entries
• Test before merging - Ensure all CI checks pass
• Coordinate deployments - Plan releases during appropriate windows
• Monitor releases - Watch for issues after deployment

Package Dependencies

• Shared package changes go in consuming app changelogs
• No separate changelogs for packages/* directories
• Document impact where users will see the changes

Troubleshooting

Release PR Not Created

1. Check changelog format - Ensure YAML frontmatter is correct
2. Verify file location - Files must be in .releases/ directory
3. Check GitHub Actions - Review workflow logs for errors

Build Failures

1. Run tests locally - Ensure all tests pass before merging
2. Check Docker configs - Verify Dockerfile and build contexts
3. Validate Go modules - Ensure go.mod is properly formatted

Version Conflicts

1. Understand versioning - Go binaries share versions, Node.js apps are independent
2. Check existing versions - Use changelog status to see current state
3. Review Release PR - Verify calculated versions are correct

Examples

Simple Bug Fix

---
"@tenki/app": patch
---

Fix authentication token refresh issue

- Fixed race condition in token refresh logic
- Improved error handling for expired tokens

New Feature with Breaking Change

---
"@tenki/app": minor
"@tenki/cli": major
"@tenki/engine": minor
---

Add workspace management features

- **App**: New workspace dashboard with team management
- **CLI**: Breaking change: `tenki workspace` command restructured
- **Engine**: Added workspace isolation and resource quotas

Multi-Component Update

---
"@tenki/app": minor
"@tenki/engine": minor
"@tenki/node-agent": patch
---

Improve runner monitoring and management

- **App**: Added real-time runner status dashboard
- **Engine**: Implemented auto-scaling for custom images
- **Node Agent**: Fixed memory leak in status reporting