GitOps Runtime Release CLI

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

Installation

``bash


Using npx (no installation required)

npx @ddmaizel/gitops-runtime-release --help

Or install globally

npm install -g @ddmaizel/gitops-runtime-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

- Node.js >= 18.0.0
- GITHUB_TOKEN environment variable with repo scope
- ANTHROPIC_API_KEY environment variable (only for notes command)

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

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


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 | Anthropic API key for AI release notes |
| 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-runtime-release-cli.git
cd gitops-runtime-release-cli

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
│ └── completion.ts # Shell completion
├── 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