releasearoni

Publish GitHub releases from the command line or Node.js. Reads defaults from package.json and CHANGELOG.md (keepachangelog format) so you rarely need to pass any flags. Ships two bins: releasearoni uses the GitHub API directly via @octokit/rest, and releasearoni-gh is a thin wrapper around the gh CLI.

npm install releasearoni

CLI

Both bins share the same flags and read the same defaults. Run either from a directory that contains package.json and CHANGELOG.md.

releasearoni

Uses @octokit/rest + ghauth for authentication. No gh CLI required.

Usage: releasearoni [options]

    Example: releasearoni

    --tag-name, -t        Tag for this release
    --target-commitish, -c Commitish value for tag
    --name, -n            Release title
    --body, -b            Release body text
    --owner, -o           Repo owner
    --repo, -r            Repo name
    --draft, -d           Publish as draft (default: false)
    --prerelease, -p      Publish as prerelease (default: false)
    --workpath, -w        Path to working directory (default: cwd)
    --endpoint, -e        GitHub API endpoint URL (default: https://api.github.com)
    --assets, -a          Comma-delimited list of assets to upload
    --dry-run             Preview release without creating it (default: false)
    --no-upsert           Fail if a release for this tag already exists (default: false)
    --prompt              Prompt for confirmation before publishing (default: false)
    --no-npm-check        Skip npm auth check before publishing (default: false)
    --no-push             Skip git push --follow-tags before publishing (default: false)
    --no-build            Skip npm run build even if a build script is present (default: false)
    --help, -h            Show help
    --version, -v         Show version

releasearoni (v0.0.0)

releasearoni-gh

Delegates to gh release create. Requires the gh CLI to be installed and authenticated.

Usage: releasearoni-gh [options]

    Example: releasearoni-gh

    --tag-name, -t        Tag for this release
    --target-commitish, -c Commitish value for tag
    --name, -n            Release title
    --body, -b            Release body text
    --owner, -o           Repo owner
    --repo, -r            Repo name
    --draft, -d           Publish as draft (default: false)
    --prerelease, -p      Publish as prerelease (default: false)
    --workpath, -w        Path to working directory (default: cwd)
    --endpoint, -e        GitHub API endpoint URL (default: https://api.github.com)
    --assets, -a          Comma-delimited list of assets to upload
    --dry-run             Preview release without creating it (default: false)
    --no-upsert           Fail if a release for this tag already exists (default: false)
    --prompt              Prompt for confirmation before publishing (default: false)
    --no-npm-check        Skip npm auth check before publishing (default: false)
    --no-push             Skip git push --follow-tags before publishing (default: false)
    --no-build            Skip npm run build even if a build script is present (default: false)
    --help, -h            Show help
    --version, -v         Show version

releasearoni-gh (v0.0.0)

Defaults

Both bins derive release defaults automatically:

| Field | Default source | |---|---| | tag_name | v + version from package.json | | name | Same as tag_name | | body | Latest versioned entry from CHANGELOG.md | | target_commitish | Current HEAD commit SHA (git rev-parse HEAD) | | owner / repo | Parsed from repository field in package.json | | draft | false | | prerelease | false | | endpoint | https://api.github.com |

The CHANGELOG.md must be in keepachangelog format. Releases are blocked if an [Unreleased] section contains content.

If a release for the tag already exists (e.g. when re-running a failed publish), both bins will update the existing release in place rather than failing. Pass --no-upsert to get a hard failure instead, which is useful for enforcing that a tag is never accidentally re-released.

releasearoni npm-check

Checks whether you are logged in to npm. If not logged in and the CI environment variable is not set, runs npm login interactively. In CI, exits non-zero with an actionable error if not authenticated. Designed to run at the top of a prepublishOnly script so login issues are caught before any build, push, or release work has started.

Usage: releasearoni npm-check

Typical package.json setup:

{
  "scripts": {
    "prepublishOnly": "releasearoni"
  }
}

releasearoni version

Generates CHANGELOG.md via auto-changelog and stages it with git add. Designed for use as the npm version lifecycle script.

Usage: releasearoni version [options]

    --changelog, -c       Changelog file to generate and stage (default: CHANGELOG.md)
    --add, -a             Additional files to stage after changelog (repeatable)
    --breaking-pattern    Regex for breaking changes (default: 'BREAKING CHANGE:')
    --template            auto-changelog template (default: keepachangelog)
    --workpath, -w        Working directory (default: cwd)
    --help, -h            Show help

Typical package.json setup — no separate auto-changelog install needed:

{
  "scripts": {
    "preversion": "releasearoni preversion",
    "version": "releasearoni version",
    "prepublishOnly": "releasearoni"
  }
}

Run npm version patch (or minor/major) and npm will:

1. Run releasearoni preversion → verifies the working tree is clean, dumps git diff if not
2. Bump the version in package.json
3. Run releasearoni version → regenerates CHANGELOG.md and stages it
4. Commit and tag

Then npm publish triggers prepublishOnly, which checks npm auth, pushes the tag, and creates the GitHub release.

To stage extra files (e.g. a lock file your project manages separately):

"version": "releasearoni version --add package-lock.json"

releasearoni preversion

Checks that the git working tree is clean before npm version runs. If anything is dirty, prints git status and git diff HEAD so you can see exactly what needs to be addressed, then exits non-zero. Designed for use as the npm preversion lifecycle script.

Usage: releasearoni preversion [options]

    --workpath, -w        Working directory (default: cwd)
    --help, -h            Show help

Without this, a dirty working tree produces npm's terse Git working directory not clean. error with no indication of what is actually dirty — especially painful in CI where you can't inspect the workspace interactively.

Example setup

A complete package.json wired up for versioning and publishing via GitHub Actions:

{
  "name": "my-package",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/my-org/my-package.git"
  },
  "scripts": {
    // Runs before `npm version`: verifies the working tree is clean
    "preversion": "releasearoni preversion",
    // Runs during `npm version`: regenerates CHANGELOG.md and stages it
    // Use --add to stage additional files that should be part of the version commit
    "version": "releasearoni version --add dist/manifest.json --add src/generated/version.js",
    // Runs before `npm publish`:
    //   1. checks npm login / OIDC status
    //   2. runs `npm run build` if a build script is present
    //   3. pushes the version commit + tag to GitHub
    //   4. creates the GitHub release
    // Use releasearoni-gh instead if you prefer the gh CLI.
    "prepublishOnly": "releasearoni",
    // Clean up build artifacts after npm has published them
    "postpublish": "npm run clean"
  },
  "devDependencies": {
    "releasearoni": "^0.1.0"
  }
}

releasearoni and releasearoni-gh are interchangeable in the scripts above — swap in releasearoni-gh if you prefer to delegate to the gh CLI.

A matching GitHub Actions workflow that triggers on manual dispatch:

# .github/workflows/release.yml
name: npm bump

on:
  workflow_dispatch:
    inputs:
      version_type:
        description: 'Version type'
        type: choice
        options: [major, minor, patch]
        default: patch
        required: true

permissions:
  contents: write # required to push the version commit, tag, and create the GitHub release
  id-token: write # required for OIDC publishing to npm (provenance)

jobs:
  version_and_release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # fetch full history so things like auto-changelog work properly
      - uses: actions/setup-node@v6
        with:
          node-version-file: package.json
      - run: npm install
      - run: npm test
      - name: Configure git author
        run: |
          git config user.name "${{ github.actor }}"
          git config user.email "${{ github.actor }}@users.noreply.github.com"
      - name: npm version
        run: npm version "${{ github.event.inputs.version_type }}"
      - name: npm publish
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # used by releasearoni to create the GitHub release
        run: npm publish

npm version runs the preversion / version lifecycle scripts (changelog + commit + tag), then npm publish triggers prepublishOnly which pushes the tag and creates the GitHub release.

Environment variables (releasearoni only)

Authentication for the direct API bin is resolved in this order:

• GH_TOKEN
• GITHUB_TOKEN
• Interactive GitHub device flow via ghauth — opens a browser prompt, stores the token in the OS keychain for future runs. Press Enter at the device flow prompt to fall back to pasting a personal access token instead.

API

import { createRelease } from 'releasearoni'

Programmatic release creation using @octokit/rest.

release = await createRelease(options)

Create a GitHub release. Reads package.json and CHANGELOG.md from workpath to fill in defaults, then calls the GitHub Releases API.

import { createRelease } from 'releasearoni'

const release = await createRelease({
  auth: { token: process.env.GITHUB_TOKEN },
  workpath: process.cwd(), // optional, defaults to cwd
})

console.log(release.html_url)

Options:

| Option | Type | Description | |---|---|---| | auth | { token: string } | Required. GitHub API token. | | workpath | string | Path to directory with package.json and CHANGELOG.md. Default: cwd. | | owner | string | Repo owner. Default: parsed from package.json. | | repo | string | Repo name. Default: parsed from package.json. | | tag_name | string | Tag to create. Default: v + package version. | | target_commitish | string | Branch or SHA for the tag. Default: current HEAD. | | name | string | Release title. Default: same as tag_name. | | body | string | Release body. Default: latest CHANGELOG entry. | | draft | boolean | Publish as draft. Default: false. | | prerelease | boolean | Mark as prerelease. Default: false. | | endpoint | string | GitHub API base URL. Default: https://api.github.com. | | assets | string[] \| {name, path}[] | Files to upload as release assets. | | upsert | boolean | Update existing release if tag already exists. Default: true. Pass false to fail instead. |

Returns the GitHub release object from the API response.

See also

• gh-release — the original CLI this was forked from
• gh CLI — official GitHub CLI used by releasearoni-gh
• keepachangelog — CHANGELOG format expected by releasearoni
• ghauth — OAuth token management used by releasearoni

License

MIT