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

``bash


Using npx (no installation required)

npx @codefresh-io/gitops-release --help

Or install globally

npm install -g @codefresh-io/gitops-release
gitops-release --help
`

$3

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 flags] [args]
`

$3

| Flag | Description |
|------|-------------|
| --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

$3

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

`bash


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 | 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

$3

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

`bash


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
`

$3

Publish a release by merging the prepare-release PR.

`bash


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

$3

List releases and their states.

`bash


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 | Number of releases to show (default: 10) |
| --include-drafts | Include draft releases |

$3

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

`bash


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

$3

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

`bash


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

$3

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

`bash


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

$3

Generate shell completion script.

`bash


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

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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.

$3

`bash


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

`bash


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

$3

Set the GITHUB_TOKEN environment variable:

`bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
`

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

$3

The notes command requires an Anthropic API key:

`bash
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
`

$3

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

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

$3

The stable branch was already created. Check its status:

`bash
gitops-release status 0.27
`

$3

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

`bash
gitops-release status 0.27
`

$3

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

`bash
gitops-release status 0.27


Check the PR URL in the output


``

License

MIT