gh-changelogen

📜 Changelog generator for GitHub Releases

🌟 Features

• Generate a changelog from an existing published GitHub Release.
• Generate release notes for a future tag before its GitHub Release exists.
• Update a tag section idempotently without changing unrelated changelog content.
• Use the CLI or the package API from a release tool such as bumpp.

🚀 Usage

From an existing GitHub Release

Published Release mode remains the default. It uses the Release’s actual name, publication time,
URL, and body.

GH_TOKEN="$(gh auth token)" npx gh-changelogen \
  --repo=kazupon/gh-changelogen \
  --tag=v1.0.0

Before creating a GitHub Release

Pass --generate-notes to call GitHub’s Generate release notes API for a future tag. The target
is resolved locally to an exact commit SHA before the request. It defaults to HEAD.

GH_TOKEN="$(gh auth token)" npx gh-changelogen \
  --repo=kazupon/gh-changelogen \
  --tag=v1.1.0 \
  --generate-notes \
  --target=HEAD \
  --output=CHANGELOG.md

Generated mode uses the operation start time in UTC and the future canonical Release URL. It only
generates notes and updates the changelog: it does not create a commit, tag, push, or GitHub
Release.

Running the command again for the same repository and tag replaces that tag’s top-level section,
or performs no write when it is already identical. If more than one matching section exists, the
command stops without changing the file. Passing --target without --generate-notes is an
error.

The generated entry has the same format in both modes:

# v1.1.0 (2026-08-03T01:02:03.456Z)

This changelog is generated by [GitHub Releases](https://github.com/kazupon/gh-changelogen/releases/tag/v1.1.0)

## What's Changed

- A released feature

Options

Option	Default	Applies to	Description
--repo <owner/repo>	required	both	GitHub repository
--tag <tag>	required	both	Existing or future Release tag
--token <token>	environment	both	Explicit GitHub token; using an environment variable is safer
--output <file>	CHANGELOG.md	both	Output resolved relative to the current working directory
--generate-notes	false	generated	Use generated notes instead of fetching a published Release
--target <commitish>	HEAD	generated	Local commitish resolved to an exact commit SHA

🔐 Authentication

Tokens are resolved in this order:

1. --token
2. GH_TOKEN
3. GITHUB_TOKEN

Environment variables are recommended because --token can leave the token in shell history and
process arguments. A local bumpp invocation does not automatically receive the GitHub Actions
GITHUB_TOKEN; provide a fine-grained PAT, GitHub App token, or GitHub CLI token explicitly.

GitHub’s
Generate release notes endpoint
requires Contents: write permission for the target repository. Published mode needs access to
read the Release. Tokens are never written to the changelog or included in request errors.

📦 Programmatic API

The package root exports generateGithubReleaseNotes and updateChangelog for ESM and CommonJS.

import { generateGithubReleaseNotes, updateChangelog } from 'gh-changelogen'

const notes = await generateGithubReleaseNotes({
  repository: 'kazupon/gh-changelogen',
  tagName: 'v1.1.0',
  targetCommitish: 'HEAD'
})

const result = await updateChangelog({
  repository: 'kazupon/gh-changelogen',
  tagName: 'v1.1.0',
  source: 'generated-notes',
  targetCommitish: 'HEAD',
  output: 'CHANGELOG.md'
})

console.log(notes.targetCommitish)
console.log(result.action) // created | prepended | replaced | unchanged

generateGithubReleaseNotes resolves the commitish, requests the notes, and returns normalized
data without changing a file. updateChangelog performs the same acquisition and atomically
updates the output. Its source defaults to published-release.

⬆️ bumpp integration

bumpp runs its execute hook after updating version
files and before creating the release commit and tag. This lets the version and changelog changes
enter the same commit.

Before releasing:

• Start with a clean working tree on the intended release branch.
• Ensure HEAD is already available on the GitHub remote. Generated notes cannot target an
  unpushed commit.
• Track CHANGELOG.md before the release. git commit --all does not add untracked files.
• Do not carry unrelated tracked changes: all: true includes every tracked change.
• Ensure the future tag does not already exist locally or remotely.
• Set GH_TOKEN or GITHUB_TOKEN with Contents: write permission.

Function hook

The function hook is the recommended integration because bumpp provides the selected version as
operation.state.newVersion.

// bump.config.ts
import { defineConfig } from 'bumpp'
import { updateChangelog } from 'gh-changelogen'

export default defineConfig({
  all: true,
  execute: async operation => {
    await updateChangelog({
      repository: 'kazupon/gh-changelogen',
      tagName: `v${operation.state.newVersion}`,
      source: 'generated-notes',
      targetCommitish: 'HEAD',
      output: 'CHANGELOG.md'
    })
  }
})

all: true is required so the already-tracked CHANGELOG.md changed by the hook is included in
the release commit.

--execute with the CLI

bump.config.ts is not required. If the release version is known before invoking bumpp, pass the
same shell variable to bumpp and gh-changelogen. This example assumes local package binaries are
on PATH, as they are inside an npm package script.

release_version=1.1.0

GH_TOKEN="$(gh auth token)" bumpp "$release_version" \
  --all \
  --execute "gh-changelogen --repo=kazupon/gh-changelogen --tag=v${release_version} --generate-notes --target=HEAD --output=CHANGELOG.md"

bumpp does not expand {version}, {tag}, or %s inside the execute command. The outer shell
expands ${release_version} before bumpp starts. Do not use an unexpanded template such as
--tag=v{version} in --execute.

When the version is selected interactively, call a wrapper that reads the manifest after bumpp has
updated it:

{
  "scripts": {
    "release": "bumpp --all --execute \"node scripts/generate-changelog.mjs\""
  }
}

// scripts/generate-changelog.mjs
import { execFileSync } from 'node:child_process'
import { readFileSync } from 'node:fs'
import { createRequire } from 'node:module'
import { dirname, resolve } from 'node:path'

const require = createRequire(import.meta.url)
const project = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
const ghPackageEntry = require.resolve('gh-changelogen')
const ghCli = resolve(dirname(ghPackageEntry), '..', 'cli.mjs')

execFileSync(
  process.execPath,
  [
    ghCli,
    '--repo=kazupon/gh-changelogen',
    `--tag=v${project.version}`,
    '--generate-notes',
    '--target=HEAD',
    '--output=CHANGELOG.md'
  ],
  { stdio: 'inherit' }
)

The wrapper passes an argument array without constructing another shell command. A non-zero
gh-changelogen exit stops bumpp before commit, tag, and push.

Releasing gh-changelogen itself

This repository uses its local CLI in the same prerelease flow:

GH_TOKEN="$(gh auth token)" vp run release

The release script first builds the local CLI. bumpp then updates package.json and invokes that
CLI with the selected future version, --generate-notes, and --target=HEAD. Its all: true
configuration puts the version and CHANGELOG.md changes in the same release commit before
creating and pushing the tag.

If changelog generation fails, bumpp stops before commit, tag, and push. Start from a clean main
branch whose HEAD is already available on GitHub.

GitHub Actions

For this repository, the tag-push workflow publishes the package first and creates the GitHub
Release only after npm publication succeeds. It does not generate or commit CHANGELOG.md;
that file is already part of the tagged release commit produced by vp run release.

The workflow’s release-notes dispatch option remains available to retry GitHub Release creation
for an existing tag without republishing the package.

Failure and recovery

Failure	State	Recovery
Token is missing	Output is unchanged	Set a token and rerun
Target SHA is not on GitHub	Output is unchanged	Push the release branch HEAD or correct --target
GitHub API request fails	Version files may be dirty; no changelog write, commit, or tag	Correct the request or permissions and rerun bumpp
Changelog validation or write fails	Original changelog remains; no commit or tag	Fix duplicate sections, paths, or permissions and rerun
bumpp fails after the hook	Version and changelog can both be dirty; no completed release	Fix the failure and restart or resume the release operation

gh-changelogen exits non-zero on failure so bumpp does not continue to commit, tag, or push. The
tag-level idempotency makes retrying the same release safe after correcting the cause.

💪 Motivation

GitHub Releases are a useful source of generated notes, but not everyone reads Release pages.
gh-changelogen keeps the repository changelog synchronized while allowing GitHub’s release notes
generation to remain the source of truth.

🙌 Contributing guidelines

If you are interested in contributing, see the
contributing guidelines for development setup and pull request guidance.

©️ License

MIT