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