# vercel/release: Generating GitHub Release Notes from Commits > vercel/release is a Node.js command line tool that turns the commits since your last tag into a GitHub Release. It is small, MIT licensed, and last pushed on 2026-05-21, so the version on npm is not the state of the repository. **vercel/release** — Generate changelogs with a single command - Repository: https://github.com/vercel/release - Website: https://npmjs.com/release - Stars: 3,584 · Forks: 117 - Language: JavaScript - License: MIT - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/vercel-release ## The problem vercel/release solves for GitHub-centric teams The README explains the origin directly: Vercel moved its repositories away from keeping a HISTORY.md file and toward GitHub Releases, and needed a way to generate those releases from a terminal rather than opening a browser page and typing notes for every change. That is the whole scope. The tool takes the commits made since the last release, formats them, and creates a GitHub Release with that text. It is aimed at maintainers of GitHub repositories who tag versions and who write commit messages that a machine can group. If your release notes are a marketing document, or if your history is a stream of "fix stuff" commits, the output will be as useful as the input. The tool does not read a changelog file, does not infer intent from diffs, and does not consult issue trackers. It reads git state and commit messages. ## How release builds a release: git state, commit parsing, Octokit The dependency list in package.json is the clearest description of the mechanism. git-state and git-spawned-stream read the local repository; tagged-versions and semver determine the current version and the next one; git-repo-name and git-username identify the repository and the local author. The commits since the latest release are collected, then grouped by change type. The resulting markdown is sent to GitHub through @octokit/rest 15.2.6, and the authentication flow lives in a separate repository, vercel/release-auth, which the README links under Contributing. Change types come from two places. If you pass major, minor or patch on the command line, that is the type for the release. If you want per-commit control, the README says to put the type in the title or description of the commit inside parentheses, as in "Error logging works now (patch)". A commit marked with the keyword ignore, again in parentheses, is excluded from the list. When a commit has no declared type, the tool asks you to set one, which is why inquirer is a dependency. The hook is the escape hatch. release looks for release.js in the project root by default, and that file exports an async function taking markdown and metaData and returning a String. The README's table lists metaData as changeTypes, commits, groupedCommits and authors, where authors are the GitHub usernames of the release collaborators. A custom path can be given with --hook or -H, resolved relative to the current working directory. That is enough to prepend an intro, reorder entries, or rewrite a section before the release is created. ## Installing vercel/release and creating a first release The README gives two install paths. The npm one is the primary: ```bash npm install -g release ``` Yarn users get the equivalent global install: ```bash yarn global add release ``` After that, run the command inside your project directory. With no argument, the README says a GitHub Release is created from the most recent commit and tag: ```bash release ``` To advance the version, pass one of the SemVer types. A patch release for backwards-compatible fixes looks like this: ```bash release patch ``` The README lists major for incompatible API changes and minor for backwards-compatible additions. Pre-releases have their own form, and the suffix defaults to canary: ```bash release pre ``` A custom suffix replaces canary. Passing beta produces a version in the 3.0.0-beta.1 shape: ```bash release pre beta ``` You should expect the tool to inspect the repository, collect commits since the last tag, and either prompt you for types on commits that lack one or proceed straight to creating the release. Run release help for the full option list. For a first real use, the lowest-risk path is a repository with a tag, a handful of commits since it, and a commit message that already carries a type in parentheses. ## Where vercel/release stops being the right tool The first limitation is visible in the version numbers. The recent releases are 6.3.0 on 2020-07-28, 6.2.0 on 2020-07-27, and 6.3.1 on 2022-03-18. The repository's last push was on 2026-05-21, which is more recent than the last published release by years, so the npm package and the default branch are not the same thing. Anyone installing from npm gets 6.3.1, and the README does not document what has changed since. The dependency tree is the second limitation. It pins @octokit/rest at 15.2.6, node-fetch at 2.6.1, semver at 5.7.2, and eslint at 4.19.1 in devDependencies. Those are old major lines. For a globally installed CLI run by a maintainer on a laptop this is a smaller concern than for a library pulled into a service, but it is a real one, and the README says nothing about upgrade policy or security reporting. The third is the model itself. Release notes are only as structured as your commits. If your team squashes merges with free-form messages, the parenthetical convention will not be there, and you will be answering inquirer prompts for every commit. The README does not document rollback: if a release is created with the wrong notes, there is no described command to undo it, so you would edit or delete the release on GitHub. And if your project is not on GitHub, or your releases are not tag-driven, none of the mechanism applies. ## vercel/release compared with semantic-release and changesets The closest alternative is semantic-release, which also derives version numbers and release notes from commits, but takes a different position on control. semantic-release runs in CI on every push to the main branch and decides on its own whether a release is needed, based on commit message conventions. vercel/release does the opposite: a human runs release patch locally, and the tool creates the release. That difference matters for teams that want a person to look at the notes before they are published, and it matters against teams that want releases to happen without anyone remembering to run a command. Changesets splits the work differently again. Instead of reading commit messages, contributors write a small markdown file describing the change alongside their pull request, and those files are consumed at release time. That is more writing per change and less guessing at release time, which suits monorepos where a single commit can touch several packages. vercel/release has no equivalent of a changeset file in the README; its only structured input is the commit message and the release.js hook. ## Licence, maintenance and what an upgrade costs The package is MIT licensed, declared in package.json and in LICENSE.md at the repository root. MIT permits use, modification and redistribution with the licence and copyright notice retained. That is the extent of what the repository states; it says nothing about trademarks, and nothing here should be read as legal advice. On maintenance, the honest summary is that the last push to the default branch was on 2026-05-21, while the newest published release is 6.3.1 from 2022-03-18. The repository is not archived. Release cadence on npm has been quiet for years, and the README does not describe a support window or a deprecation path. If you install globally, the upgrade cost is mostly the cost of re-testing your release.js hook against whatever the current npm version does, since the hook signature is the part of the tool your project actually depends on. Pin the version you install if you care about that, and read the hook contract before upgrading rather than after. ## Conclusion Adopt vercel/release if your project already lives on GitHub, your history is reasonably clean, and you want release notes generated from commit messages instead of written by hand. Do not adopt it if you need a maintained dependency tree, if your release process is not tag-driven, or if your commits are not written with the parenthetical type convention. Before installing, verify that the package you get from npm matches the repository, and read the release.js hook contract so you know what markdown and metaData contain. ## FAQ ### How do I install vercel/release? Install it globally from npm with npm install -g release, or with yarn global add release. Then run release inside your project directory. The README also describes npm link for working on the package itself. ### What is vercel/release used for? It is a command line tool that automatically generates a new GitHub Release and populates it with the commits made since the last release. Vercel built it after moving its repositories from HISTORY.md files to GitHub Releases. ### How do I tell vercel/release what kind of change a commit is? Add the type in parentheses to the commit title or description, for example "Error logging works now (patch)". The README states that release then skips asking you to set a type manually. Use the keyword ignore in parentheses to exclude a commit from the list. ### Can I change the release notes before they are published? Yes, with a custom hook. By default release looks for release.js in the project root, which exports an async function receiving markdown and metaData and returning the final release as a String. The README notes that --hook or -H sets a different path relative to the current working directory. ### Does vercel/release support pre-releases? Yes. Running release pre creates a pre-release, and the README gives 3.0.0-canary.1 as the default shape. A custom suffix can be supplied, so release pre beta produces a version like 3.0.0-beta.1. ## Sources - [License: MIT](https://github.com/vercel/release/blob/master/LICENSE) - [Project website](https://npmjs.com/release) - [README](https://github.com/vercel/release/blob/master/README.md) - [Releases](https://github.com/vercel/release/releases) - [vercel/release on GitHub](https://github.com/vercel/release) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vercel-release