Yaba GitHub Release CLI

Yaba is a simple CLI tool that helps you manage releases of your GitHub projects.

Documentation

• Architecture
• Development Guide
• GitHub Pages Site

Prerequisites

You need npm in order to run the project on your local environment.

Installing / Updating / Uninstalling

To install CLI package globally:

npm i -g yaba-release-cli

To Update:

npm update -g yaba-release-cli

To uninstall:

npm uninstall -g yaba-release-cli

Setup

Create Personal Access Token

Go to Personal Access Tokens page on GitHub and generate new token to enable yaba CLI to access your repos.

• Give your desired name to your personal access token with Note section.
• Choosing repo scope is enough to use yaba CLI tool.

Now, your personal access token is generated. Copy that token and define that one as an environment variable:

export YABA_GITHUB_ACCESS_TOKEN=generated_personal_access_token

You can define that env variable into ~/.bashrc, ~/.bash_profile or ~/.zshrc file, choose which one is suitable for you. After defining the env variable, open new terminal or simply run source ~/.zshrc(here again choose where you defined your env variable).

If the repository owner is another GitHub account or organisation, you can define that like below instead of passing the owner to the command in every run.

export YABA_GITHUB_REPO_OWNER=repository_owner

Always -o or --owner has precedence over authenticated user. Presendence is like -o > GITHUB_REPO_OWNER > authenticated-user.

Slack Integration

If you want to announce your release/changelog to the specific Slack channel, you have to define below environment variable with the appropriate value.

export YABA_SLACK_HOOK_URL=your_slack_hook_url

Also, multiple hook URLs allowed to be defined like below:

export YABA_SLACK_HOOK_URL=your_slack_hook_url_1,your_slack_hook_url_2,...

If the above variable is set and the -p command given while running the command, an announcement will be post to the given Slack channel. You can find detailed information in the Command Line Usage section.

yaba release create -p

Slack publish now retries transient failures with exponential backoff (default: max 3 attempts).

Notification providers are now resolved through config. Slack remains provider #1:

{
  "notifications": {
    "providers": ["slack"],
    "slack": {
      "enabled": true
    }
  }
}

Release note rendering is channel-specific:

• GitHub release notes: grouped by PR labels when available. Teams can customize label-to-section mappings via release.labelBuckets in yaba.config.json (see CONFIG.md for details). Default grouping includes: type:feature, type:fix, type:docs, type:breaking, dependencies/deps.
• Slack release notes: rendered as a short newsletter for human readers.
• Fallback: if label metadata is missing, GitHub notes fall back to the legacy commit-list structure.

Custom label buckets example:

{
  "release": {
    "labelBuckets": [
      {
        "key": "security",
        "title": "Security Fixes",
        "labels": ["security", "type:security"]
      },
      {
        "key": "chore",
        "title": "Chore",
        "labels": ["chore", "type:chore"]
      }
    ]
  }
}

For complete configuration details, see CONFIG.md.

Command Line Usage

Run yaba with --help options:

➜  ~ yaba --help
Usage: yaba <release|doctor|config> [options]

Options:
  -o, --owner                 The repository owner.                      [string]
  -r, --repo                  The repository name.                       [string]
  -t, --tag                   The name of the tag.                       [string]
      --tag-strategy          Tag generation strategy.
                              [choices: "pattern", "semver", "sha"]
                              [default: from config (fallback: pattern)]
      --tag-on-conflict       How to handle already existing tags.
                              [choices: "increment", "fail"]
                              [default: from config (fallback: increment)]
      --tag-max-attempts      Maximum attempts while resolving a unique tag with increment policy.
                                                                       [number]
                              [default: from config (fallback: 20)]
      --target                Target commit-ish (branch, tag, or SHA) to generate
                              and create the release from.               [string]
      --allow-empty           Allow creating a release when no commits are found
                              in changelog comparison.                  [boolean]
      --fail-on-empty         Fail when no commits are found in changelog
                              comparison.                               [boolean]
      --max-commits           Fail when commit count exceeds this limit. [number]
  -n, --name, --release-name  The name of the release.                   [string]
  -b, --body          Text describing the contents of the tag. If not provided,
                      the default changelog will be generated with the usage of
                      the difference of default branch and latest release.
                                                                       [string]
  -d, --draft                 Creates the release as draft.             [boolean]
  -c, --changelog     Shows only changelog without creating the release.
                                                                       [boolean]
  -i, --interactive           Prompt before (draft) release is created (default true)
                                                                       [boolean]
      --yes                   DEPRECATED: Skip confirmation prompt and create
                              release directly. Use --no-prompt.        [boolean]
      --no-prompt             Skip release confirmation prompt (same as --yes).
                                                                       [boolean]
      --notify                DEPRECATED: Send notifications after release is
                              created. Use --publish. [choices: "slack"]
  -p, --publish               Publishes the release announcement to the defined Slack
                              channel                                   [boolean]
      --format                Output format.
                              [choices: "human", "json"]
      --config                Path to config file.                        [string]
      --force                 Overwrite generated files when they already exist.
                                                                       [boolean]
  -h, --help                  Show help                                 [boolean]
  -v, --version               Show version number                       [boolean]

Supported commands:

• yaba release create: creates a release on GitHub.
• yaba release preview: prepares and prints release details without creating a release.
• yaba doctor: runs environment and connectivity diagnostics.
• yaba config init: creates a yaba.config.json template in the current directory.
• yaba config validate: validates resolved config values and reports schema issues.

Create release with the new command format:

yaba release create --repo my-repo --publish --no-prompt

Create release from a specific commit/tag/branch target:

yaba release create --repo my-repo --target 1a2b3c4d --no-prompt

Fail explicitly when no changes are found:

yaba release create --repo my-repo --fail-on-empty --no-prompt

Allow empty release intentionally:

yaba release create --repo my-repo --allow-empty --no-prompt

Preview release details without side effects:

yaba release preview --repo my-repo

Preview release details in JSON format:

yaba release preview --repo my-repo --format json

Preview release details from a specific target reference:

yaba release preview --repo my-repo --target release/2.x

Create release using semver tag strategy (v<package.json version>):

yaba release create --repo my-repo --tag-strategy semver --no-prompt

Create release using sha-based tag strategy:

yaba release create --repo my-repo --tag-strategy sha --target 1a2b3c4d5e6f --no-prompt

Run setup diagnostics:

yaba doctor

Run setup diagnostics in JSON format:

yaba doctor --format json

yaba doctor now reports:

• token type (GitHub Actions token, fine-grained PAT, classic PAT, or unknown),
• OAuth scope summary when available,
• repository access check results with actionable remediation guidance.

Create local config template:

yaba config init

Overwrite existing config template:

yaba config init --force

Create config template at a custom location:

yaba config init --config ./config/yaba.config.json

Validate config at a custom location:

yaba config validate --config ./config/yaba.config.json

Validate config in JSON format:

yaba config validate --config ./config/yaba.config.json --format json

When --format json is used, yaba prints machine-readable command results to stdout and errors to stderr.

Config precedence for runtime values is:

flags > env vars > project config (./yaba.config.json) > user config (~/.config/yaba/config.json) > defaults

You can run yaba from a git directory or any other directories which is not a git repo.

If you are in a git repo and if you want to prepare the release for that repo, you don't need to specify the repo name with the command. The command will try to detect the repository name from remote.origin.url and use it as repo for the command.

By default, if you don't specify -o, -t, -n and -b the command will prepare default values for them with the below pattern:

-o: authenticated_user
-t: prod_global_YYYYMMDD.1
-n: Global release YYYY-MM-DD
-b: Commits between last release and default branch

If a repository has no previous release, yaba now falls back to the head branch for changelog comparison and still prepares the release.

Deprecations (v2 compatibility)

The following legacy invocations are still supported in v2, but emit deprecation warnings in human-readable output and are planned for removal in v3:

• --yes -> use --no-prompt
• --notify slack -> use --publish
• --release-name -> use --name
• implicit yaba command -> use yaba release create

For automation scripts, migrate now to avoid v3 breakage.

Exit Codes

yaba now returns deterministic exit codes for automation/CI usage:

0 = success
1 = validation/config/user-input error
2 = authentication/authorization error
3 = network/connectivity error
4 = upstream API error
5 = partial success (release created, notification failed)
6 = unexpected internal error

Run Locally

You have to clone the repository to your local machine

git clone [email protected]:volkanto/yaba.git

Go to project folder

cd yaba

Build dependencies

npm install

You have to install globally in order to run your yaba command

npm install -g .

Run unit tests:

npm run test:unit

Run integration tests:

npm run test:integration

Issues

You can create an issue if you find any problem or feel free to create a PR with a possible fix or any other feature. Also, you can create an issue if you have any idea that you think it will be nice if we have it.

Authors

• Volkan Tokmak - volkanto