Skill: Release Management (rls)

Prerequisites

tnctl CLI: Install the TrueNorth control CLI
```
pip install tnctl
```
Requires Python 3.10+. Authenticate with tnctl auth login after install.
GitHub access: gh CLI authenticated with access to TrueNorth repos (for cherry-pick/hotfix workflows)
Repo clones: Repos must be cloned via /codebase clone for tag/diff operations that inspect local git history

Purpose

Manage TrueNorth service releases using tnctl rls - create release tags, monitor deployment status, view diffs, and generate release notes.

When to Use

Tagging new releases for deployment
Checking deployment/release status
Viewing what changes will be released
Generating release notes for communication
Monitoring rollout progress

AI Agent Guidelines

Invoke skill first: Before running any tnctl rls commands, invoke this skill using Skill(truenorth-rls) to activate permissions. Otherwise commands will require manual approval.

Always use structured output:

Use --output json for all commands (default is table which is CLI-formatted)
Parse JSON responses for programmatic decisions
Avoid watch - use polling with JSON output instead

Command purpose:

status - Overview of all services deployment state
diff --repo=<repo> - Detailed changes for a single repo (commits, authors, etc.)
note - Summary across all repos with pending changes
list - Historical release tags for a repo

Commands

`tnctl rls status`

Check deployment status of services.

# All services (JSON)
tnctl rls status --output json

# Specific repo (JSON)
tnctl rls status --repo=truenorth-web --output json

# Filter by service name
tnctl rls status --service=deployments/discovery-agents --output json

Options:

--repo TEXT - Filter by repository slug
--service TEXT - Filter services (comma-separated)
--output json - Always use for AI

Polling pattern (instead of watch):

# Poll every few seconds, parse JSON to check if deployment complete
tnctl rls status --repo=truenorth-web --output json
# Check status field in response, repeat until desired state

`tnctl rls diff`

Show detailed changes for a single repository between production and target.

Use this to see exactly what commits/changes will be released for a specific repo.

# See pending changes for a repo (JSON)
tnctl rls diff --repo=truenorth-web --output json

# Compare specific versions
tnctl rls diff --repo=truenorth-web --from v1.4-202512042255 --to v1.5-202512050841 --output json

# Filter by service (for multi-service repos)
tnctl rls diff --repo=discovery-agents --service=deployments/discovery-agents --output json

Options:

--repo TEXT - Repository slug (required)
--from TEXT - Start commit/tag (default: latest release tag)
--to TEXT - End commit/tag (default: main)
--service TEXT - Service name if repo has multiple services
--output json - Always use for AI

`tnctl rls note`

Generate release notes summary across all repos (or filtered repos).

Use this to get a quick overview of what's pending across the platform, not for detailed single-repo analysis.

# All repos overview (JSON)
tnctl rls note --output json

# With commit details
tnctl rls note --show-diff --output json

# Markdown output (for documentation/sharing)
tnctl rls note --output md --show-diff

Options:

--repo TEXT - Comma-separated repos (default: all)
--from TEXT - Start commit/tag (default: auto-detect from prod)
--to TEXT - End commit/tag (default: main)
--show-diff/--no-show-diff - Include commit diffs (default: no-show-diff)
--output json|md|csv - Use json for AI, md for documentation

`tnctl rls list`

List historical release tags for a repository.

# Recent releases (JSON)
tnctl rls list --repo=truenorth-web -n 5 --output json

Options:

--repo TEXT - Filter by repo slug
-n, --limit INTEGER - Number of tags to return
--output json - Always use for AI

`tnctl rls tag`

Create release tags to trigger deployment. Requires human approval.

# Dry run (preview - always do this first)
tnctl rls tag --repo=truenorth-web

# Patch release
tnctl rls tag --repo=truenorth-web --no-dryrun --push

# Minor version bump
tnctl rls tag --repo=truenorth-web --minor --no-dryrun --push

# Tag specific commit/branch
tnctl rls tag --repo=truenorth-web --target=origin/hotfix-branch --no-dryrun --push

# Multiple repos at once
tnctl rls tag --repo=data-token-price,discovery-agents,tn-app-service --minor --no-dryrun --push

Options:

--repo TEXT - Comma-separated list of repos (default: all repos)
--target TEXT - Target commit or branch (default: main)
--minor/--no-minor - Increment minor version instead of patch (default: no-minor)
--dryrun/--no-dryrun - Simulate without creating tags (default: dryrun)
--push/--no-push - Push after tagging (default: no-push)
--force/--no-force - Ignore existing release on target commit

IMPORTANT: This command triggers actual deployments. Always requires human confirmation.

Workflows

Single Repo Release (AI-friendly)

# 1. Check current status
tnctl rls status --repo=truenorth-web --output json

# 2. See what changes are pending
tnctl rls diff --repo=truenorth-web --output json

# 3. Dry run tag (human reviews)
tnctl rls tag --repo=truenorth-web

# 4. Create and push (human confirms)
tnctl rls tag --repo=truenorth-web --minor --no-dryrun --push

# 5. Poll status until deployed
tnctl rls status --repo=truenorth-web --output json

Multi-Repo Overview

# 1. Get overview of all pending changes
tnctl rls note --output json

# 2. For repos with changes, get detailed diff
tnctl rls diff --repo=<repo-from-note> --output json

# 3. Tag repos that are ready (human confirms)
tnctl rls tag --repo=repo1,repo2,repo3 --minor --no-dryrun --push

Hotfix Release (cherry-pick to prod)

When you need to release a specific commit without other pending changes on main:

# 1. Check prod state
tnctl rls status --repo=<repo> --output json
tnctl rls list --repo=<repo> -n 1 --output json

# 2. Create hotfix branch from prod tag (in repo worktree)
git checkout -b hotfix/<name> <prod-tag>
git cherry-pick <commit-hash>

# 3. Verify cherry-pick is clean — check intermediate commits don't touch same files
git log --oneline <prod-tag>..<commit> -- <files-changed-by-commit>
# Should only show the target commit itself

# 4. Push branch (REQUIRED — tnctl uses its own cache, can't see local branches)
git push -u origin hotfix/<name>

# 5. Review diff — should show ONLY the cherry-picked commit
tnctl rls diff --repo=<repo> --from <prod-tag> --to origin/hotfix/<name> --output json

# 6. Dry run tag
tnctl rls tag --repo=<repo> --target=origin/hotfix/<name> --minor

# 7. Tag and push (requires human approval)
tnctl rls tag --repo=<repo> --target=origin/hotfix/<name> --minor --no-dryrun --push

# 8. Monitor deployment
tnctl rls status --repo=<repo> --output json

Key points:

Always use a worktree (not the canonical clone) for hotfix branches
Push before rls diff or rls tag --target — tnctl can't see local-only branches
Use --minor for feature hotfixes, omit for patch-level fixes
Verify the diff shows exactly 1 commit before tagging

Monitor Deployment (Polling)

# Instead of: watch -n 3 'tnctl rls status'
# Do: Poll with JSON and check status programmatically
tnctl rls status --repo=truenorth-web --output json
# Parse response, check deployment status, sleep, repeat

Known Repositories

Common repos used in releases:

truenorth-web - Frontend
tn-app-service - Main backend service
data-token-price - Token pricing data
discovery-agents - Discovery/research agents
market-scraper - Market data scraping
market-scraper-tg - Telegram market scraper
spotlight-data-pipeline - Spotlight data processing
token-service - Token management
user-service - User management
notification-service - Notifications
llm-facade - LLM integration
data-foundation - Data infrastructure
alert-service - Alerting system

Tips

Always use --output json for AI-parseable responses
diff for single repo - Get detailed commit info for one repo
note for overview - Quick summary across all repos
Dry run first - tnctl rls tag defaults to dry run mode
Poll, don't watch - Use JSON polling instead of watch for monitoring
Minor vs patch - Use --minor for feature releases, omit for hotfixes