CLI to automate GitOps runtime release lifecycle operations
npm install @codefresh-io/gitops-releaseA 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.
``bashUsing npx (no installation required)
npx @codefresh-io/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.27Create from a specific commit
gitops-release create 0.27 --from abc1234Preview 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 statusShow detailed status for a specific version
gitops-release status 0.27JSON 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.0Skip confirmation prompt
gitops-release publish 0.27.0 --forcePreview 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 listList more releases
gitops-release list --limit 20Include draft releases
gitops-release list --include-draftsJSON 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.0Open in editor for review
gitops-release notes 0.27.0 --editApply notes to draft release and Chart.yaml
gitops-release notes 0.27.0 --applyPreview 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 abc1234Backport multiple commits
gitops-release cherry-pick 0.26 abc1234 def5678 ghi9012Preview 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 chatWith 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.272. Wait for pipeline, then check status
gitops-release status 0.273. Generate release notes (optional)
gitops-release notes 0.27.0 --edit --apply4. 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.262. 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 abc12342. 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 chatThen 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 --jsonCheck 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-releaseInstall dependencies
npm installBuild
npm run buildRun locally
npm start -- statusWatch mode
npm run devLink globally for testing
npm link
gitops-release --helpRun tests
npm testRun tests in watch mode
npm run test:watchLint
npm run lintFormat code
npm run formatType 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
``MIT