@amiramirov/release

Automate cherry-pick release workflow for Git repositories with GitLab.

Install

As a global CLI (recommended — puts release on your $PATH):

npm install -g @amiramirov/release

Or run one-off with npx — no install, latest version:

npx @amiramirov/release

Or add as a dev-dependency to a project (invoke via npx release or package.json scripts):

npm install --save-dev @amiramirov/release

Usage

From inside a Git repository with a GitLab origin:

release

The flow is step by step: every step asks first, then runs, then reports what it did. Answering No — or hitting Ctrl+C — stops right there and prints what already exists, plus the commands to undo it.

1. Ask for a GitLab Personal Access Token on first run (stored in ~/.config/release-cli/config.yml, permissions 600).
2. Fetch tags/branches from the remote.
3. Let you pick a base production tag.
4. List commits between the base tag and origin/main, hiding those already released (patch-id match).
5. Multi-select commits to include.
6. Release branch — create release/<base-tag>-<timestamp> from the base tag, cherry-pick the selected commits in a temporary worktree (your checked-out branch and uncommitted changes are never touched), then push it.
7. Merge request — open an MR from the release branch onto main, which is what gets the build/pipeline running. Prints the MR link.
8. Tag — pick a semver bump (patch/minor/major), tag the release branch HEAD and push the tag.
9. GitLab Release — set release date/time (default tomorrow 09:00 local), edit the description in $EDITOR (prefilled with commit subjects), then POST to the GitLab Releases API for the tag pushed in step 8.

Authentication

The token is all you need — git fetch, the branch push and the tag push all go through https://oauth2:<token>@<host>/<project>.git, so no SSH key, passphrase or password is ever involved. This holds even when origin is an SSH remote (git@gitlab…): only the host and project path are taken from it. Give the token the api, read_repository and write_repository scopes.

If an HTTPS operation fails on a repo whose origin is SSH, the CLI says so and retries once through origin — i.e. over your SSH key — so a token that is missing write_repository doesn't strand a half-finished release.

Options

• --remote <name> — Git remote to use (default: origin)
• --no-fetch — skip git fetch at start
• --tag-pattern <glob> — override glob for production tags (default from config, v*)
• --show-released — include commits already present in the base tag (hidden by default)

Config

~/.config/release-cli/config.yml:

gitlabUrl: https://gitlab.com
gitlabToken: glpat-...
mainBranch: main
productionTagPattern: v*
releaseBranchPattern: release/{tag}
allowMergeCommits: false

Requirements

• Node.js 20 LTS or newer
• git in PATH
• Interactive TTY (arrow-key prompts)

License

MIT