GitOps Runtime Release CLI

A TypeScript CLI to automate the release lifecycle for Codefresh GitOps runtime helm chart. The CLI performs GitHub operations that trigger existing Argo Workflows pipelines automatically.

Installation

# Using npx (no installation required)
npx @codefresh-io/gitops-release --help

# Or install globally
npm install -g @codefresh-io/gitops-release
gitops-release --help

Manual Release Process

If you prefer not to use this CLI (or don't have an Anthropic API key for AI release notes), see the Manual Release Guide in the gitops-runtime-helm repository.

Requirements

• GITHUB_TOKEN environment variable with repo scope
• ANTHROPIC_API_KEY environment variable (only for notes command)
  • Codefresh team: Find this in 1Password under "Anthropic API Key - GitOps Release CLI"

Usage

gitops-release [global flags] <command> [command flags] [args]

Global Flags

| Flag | Description | |------|-------------| | --repo <owner/repo> | Target repository (default: codefresh-io/gitops-runtime-helm) | | --json | Output as JSON | | -q, --quiet | Minimal output | | -v, --verbose | Verbose output | | --no-color | Disable colored output | | -h, --help | Show help | | -V, --version | Show version |

Commands

create <major.minor>

Create a new stable release branch. This triggers the prepare-release pipeline.

# Create stable/0.27 from main HEAD
gitops-release create 0.27

# Create from a specific commit
gitops-release create 0.27 --from abc1234

# Preview without making changes
gitops-release create 0.27 --dry-run

Options: | Flag | Description | |------|-------------| | --from <sha> | Commit SHA to branch from (default: main HEAD) | | --dry-run | Preview without making changes | | -f, --force | Skip confirmation prompt |

What happens next:

1. The prepare-release pipeline automatically creates a prep/v0.27.0 branch
2. Opens a prepare-release PR to stable/0.27
3. Creates a draft GitHub release

status [version]

Show status of releases, open PRs, drafts, and pipelines.

# Show overview of all active releases
gitops-release status

# Show detailed status for a specific version
gitops-release status 0.27

# JSON output for scripting
gitops-release status 0.27 --json

publish <version>

Publish a release by merging the prepare-release PR.

# Publish release 0.27.0
gitops-release publish 0.27.0

# Skip confirmation prompt
gitops-release publish 0.27.0 --force

# Preview without merging
gitops-release publish 0.27.0 --dry-run

Options: | Flag | Description | |------|-------------| | -f, --force | Skip confirmation prompt | | --dry-run | Preview without merging |

What happens next:

1. The promote pipeline publishes the chart to quay.io
2. Publishes the GitHub release (draft → published)
3. Signs container images

list

List releases and their states.

# List recent releases (default: 10)
gitops-release list

# List more releases
gitops-release list --limit 20

# Include draft releases
gitops-release list --include-drafts

# JSON output
gitops-release list --json

Options: | Flag | Description | |------|-------------| | -n, --limit <n> | Number of releases to show (default: 10) | | --include-drafts | Include draft releases |

notes <version>

Generate AI-powered release notes for ArtifactHub and GitHub releases.

# Generate and display notes
gitops-release notes 0.27.0

# Open in editor for review
gitops-release notes 0.27.0 --edit

# Apply notes to draft release and Chart.yaml
gitops-release notes 0.27.0 --apply

# Preview changes without applying
gitops-release notes 0.27.0 --apply --dry-run

Options: | Flag | Description | |------|-------------| | -e, --edit | Open generated notes in $EDITOR for review | | -a, --apply | Apply notes to draft release and Chart.yaml | | --dry-run | Preview without making changes |

Requirements:

• ANTHROPIC_API_KEY environment variable

cherry-pick <major.minor> <commits...>

Cherry-pick commits to a stable branch and create a PR.

# Backport a single commit
gitops-release cherry-pick 0.26 abc1234

# Backport multiple commits
gitops-release cherry-pick 0.26 abc1234 def5678 ghi9012

# Preview without making changes
gitops-release cherry-pick 0.26 abc1234 --dry-run

Options: | Flag | Description | |------|-------------| | --dry-run | Preview without making changes | | -f, --force | Skip confirmation prompt |

Requirements:

• Must be run from within a local git checkout of the repository

chat

Start an interactive AI agent for release management. Instead of memorizing CLI commands, describe what you want in natural language.

# Start the chat agent
gitops-release chat

# With verbose output (shows session info and costs)
gitops-release chat --verbose

Options: | Flag | Description | |------|-------------| | -v, --verbose | Show session details and API costs |

Requirements:

• ANTHROPIC_API_KEY environment variable
• Interactive terminal (TTY)

Example session:

$ gitops-release chat
GitOps Release Agent [Experimental]

A conversational interface for managing GitOps runtime releases.
Ask questions like:
  • "What releases are in progress?"
  • "Show me the status of v0.27"
  • "Generate release notes for 0.27.0"
  • "Create a new release branch for 0.28"

Read operations auto-execute. Write operations require confirmation.
Type 'exit' to quit.

gitops> What's the current release status?
[Agent runs gitops-release status and explains the results]

gitops> Create a new release for 0.28
The agent wants to run:
  gitops-release create 0.28

Allow this operation? (y/N)

Security:

• Read-only commands (status, list, notes) execute automatically
• Write commands (create, publish, notes --apply) require explicit confirmation
• Only gitops-release CLI commands are allowed

completion <shell>

Generate shell completion script.

# Bash completion
gitops-release completion bash > /etc/bash_completion.d/gitops-release
# Or
source <(gitops-release completion bash)

# Zsh completion
gitops-release completion zsh > ~/.zsh/completions/_gitops-release
# Then add to ~/.zshrc:
#   fpath=(~/.zsh/completions $fpath)
#   autoload -Uz compinit && compinit

Example Workflows

Create and Publish a New Minor Release

# 1. Create the stable branch
gitops-release create 0.27

# 2. Wait for pipeline, then check status
gitops-release status 0.27

# 3. Generate release notes (optional)
gitops-release notes 0.27.0 --edit --apply

# 4. When PR is ready, publish
gitops-release publish 0.27.0

Patch Release Flow

# 1. Check current status of existing stable branch
gitops-release status 0.26

# 2. If there's a pending prepare-release PR
gitops-release publish 0.26.6

Backport a Fix

# 1. Cherry-pick fix from main to stable/0.26
gitops-release cherry-pick 0.26 abc1234

# 2. Review and merge the created PR, then publish
gitops-release status 0.26
gitops-release publish 0.26.6

Using the Chat Agent

# Start the interactive agent
gitops-release chat

# Then have a conversation:
# > "What releases are in progress?"
# > "Show me the status of 0.27"
# > "The PR looks good, let's publish it"
# > "exit"

The agent understands context, so you can have natural conversations about releases without needing to remember exact command syntax.

CI/Scripted Usage

# Non-interactive publish with JSON output
GITHUB_TOKEN=$TOKEN gitops-release publish 0.27.0 --force --json

# Check if ready to publish
gitops-release status 0.27 --json | jq '.ready_to_publish'

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Generic error | | 2 | Invalid usage / bad arguments | | 3 | Git/GitHub operation failed | | 4 | Resource not found | | 5 | Cancelled by user | | 6 | AI generation failed |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GITHUB_TOKEN | Yes | GitHub API token with repo scope | | ANTHROPIC_API_KEY | For notes, chat | Anthropic API key for AI features | | NO_COLOR | No | Disable colors when set | | EDITOR | No | Editor for notes --edit (default: vim) |

Development

# Clone the repository
git clone https://github.com/codefresh-io/gitops-release.git
cd gitops-release

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- status

# Watch mode
npm run dev

# Link globally for testing
npm link
gitops-release --help

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

Project Structure

src/
├── index.ts              # CLI entry point
├── context.ts            # Shared command context
├── commands/
│   ├── create.ts         # Create stable branch
│   ├── status.ts         # Show release status
│   ├── publish.ts        # Merge prepare-release PR
│   ├── list.ts           # List releases
│   ├── notes.ts          # AI-powered release notes
│   ├── cherry-pick.ts    # Cherry-pick commits
│   ├── chat.ts           # Interactive AI agent
│   └── completion.ts     # Shell completion
├── agent/
│   ├── index.ts          # Agent module exports
│   ├── prompts.ts        # System prompt for the agent
│   ├── hooks.ts          # Permission control (canUseTool)
│   └── repl.ts           # Interactive REPL implementation
├── services/
│   ├── github.ts         # GitHub API wrapper (Octokit)
│   ├── version.ts        # Version parsing/validation
│   └── ai.ts             # Anthropic AI service
├── output/
│   └── formatter.ts      # Output formatting (human/JSON)
└── utils/
    ├── errors.ts         # Error classes with exit codes
    └── prompts.ts        # Interactive prompts

Troubleshooting

"GITHUB_TOKEN environment variable is required"

Set the GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Create a token at https://github.com/settings/tokens with repo scope.

"ANTHROPIC_API_KEY environment variable is required"

The notes command requires an Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx

"Not in a git repository"

The cherry-pick command requires a local git checkout. Clone the repository first:

git clone https://github.com/codefresh-io/gitops-runtime-helm.git
cd gitops-runtime-helm
gitops-release cherry-pick 0.26 abc1234

"Branch already exists"

The stable branch was already created. Check its status:

gitops-release status 0.27

"No prepare-release PR found"

Wait for the prepare-release pipeline to complete, or check if there's an issue:

gitops-release status 0.27

"CI checks not passing"

Fix the failing checks before publishing. View the PR for details:

gitops-release status 0.27
# Check the PR URL in the output

License

MIT