Release Drafter groups merges into categories that also decide the version bump
Drafts your next release notes as pull requests are merged into master.
At a glance
- What is it?
- Release Drafter is a GitHub Action that keeps a draft release up to date from merged pull requests, reading its configuration through the API instead of checking the repository out, and it separates three things that look like one setting: which category a merge lands in, whether it bumps the version, and whether it appears in the notes at all.
- Who is it for?
- Release Drafter can assemble release notes and resolve version increments from configurable change categories. Categories can match labels, conventional commit information or paths; an unconditional changelog category can collect otherwise uncategorized changes.
- Can I use it commercially?
- Yes. ISC is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- release-drafter/release-drafter3,954 ★ · +10
| Repository | 2026-09-26 | 2026-11-15 |
|---|---|---|
| release-drafter/release-drafter | 3.9k | 4k |
10 Stars in the last 50 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The workflow asks for two permissions and never checks the repository out
The usage section is a single workflow file. It triggers on pushes to main, runs on `ubuntu-slim`, and grants the default token two scopes: `contents: write` and `pull-requests: read`. The step itself is one line, `uses: release-drafter/release-drafter@v7`, with a single input, `config-name`, whose default loads `.github/release-drafter.yml`.
name: Release Drafter
on:
push:
branches:
- main
# Permissions for the default token.
permissions:
contents: write
pull-requests: read
jobs:
update_release_draft:
runs-on: ubuntu-slim
steps:
- uses: release-drafter/release-drafter@v7
with:
# This default loads .github/release-drafter.yml.
config-name: release-drafter.ymlThere is no checkout step, and that is deliberate rather than an oversight: the configuration file is fetched through the GitHub API, which is why the action can run as a bare step with no repository on disk.
A category can group a change, exclude it, or bump the version
The grouped example is where the mechanism actually lives. Three categories match on labels, one with `semver-increment: minor` attached so that a merge labelled feature or enhancement also pushes the minor version up. Two entries use a `type` instead of a title: `pre-exclude` drops anything labelled `skip-changelog` before templating, and two `version-resolver` entries respond to labels by setting the increment to major or to patch.
name-template: 'v$RESOLVED_VERSION 🌈'
tag-template: 'v$RESOLVED_VERSION'
categories:
- title: '🚀 Features'
semver-increment: minor
when:
labels:
- 'feature'
- 'enhancement'
- title: '🐛 Bug Fixes'
when:
labels:
- 'fix'
- 'bugfix'
- 'bug'
- title: '🗠 Maintenance'
when:
label: 'chore'
- type: 'pre-exclude'
when:
label: 'skip-changelog'
- type: 'version-resolver'
semver-increment: 'major'
when:
label: 'major'
- type: 'version-resolver'
semver-increment: 'patch'Labels can group, exclude or resolve a version; categories can also match paths or conventional commit information. A changelog category without a `when` condition can collect otherwise uncategorized changes, while an unconditional version-resolver category can serve as a fallback.
The draft name and the tag are templated separately
Two keys control what a release is called, and the example makes the split visible: `name-template` renders the draft name with a decorative emoji after the version, while `tag-template` renders the tag as the bare `v` plus the resolved version. The emoji stays in the GitHub draft list and never reaches the tag, which is the point of having two keys instead of one.
A third key, `version-template`, covers projects that do not follow Semantic Versioning, and its default is `$MAJOR.$MINOR.$PATCH$PRERELEASE`. The `$RESOLVED_VERSION` value used by the first two templates is therefore not the same string as the parts inside `version-template`; one is a number resolved from increment rules, the other is a template for how to print it.
That is also why `tag-prefix` exists. Its default is the empty string, and it exists so Release Drafter can strip a prefix before parsing an existing tag as a version, which is what lets it find the previous release to increment from.
The same package runs against four forges, one conformance target at a time
The action is only the entry point. A separate `release-drafter` package ships a command-line interface and a programmatic API for other CI systems, and it names its supported hosts: GitHub, GitHub Enterprise Server, Gitea, Forgejo and GitLab. The README points at `packages/release-drafter/README.md` for installation and API examples rather than repeating them.
The test scripts show how that support is kept honest. There is a separate conformance run per forge, `test:conformance:gitea`, `test:conformance:forgejo`, `test:conformance:gitea-forgejo` and `test:conformance:gitlab`, each selecting its target through a `FORGE_CONFORMANCE_TARGET` environment variable and its own vitest config, with `vitest.forge.config.ts` and `vitest.gitlab.config.ts` at the root. The engines field is where the cost of that shows: Node `^24.11.0 || >=26.0.0` with npm `>=12.0.1`.
The root manifest is a private workspace that commits its own dist
The root `package.json` is not the action's manifest. It is `@release-drafter/root`, described as a private workspace coordinator, at version 7.9.0 with `private: true`, which means it is never published and its version number only tracks the workspace. It declares an imports map with three aliases, `#gh-actions/*`, `#src/*` and `#tests/*`, and its build script chains a vite build for the actions with a workspace-wide build.
The tree around it explains the shape of the project: `action.yml` at the root for the action entry, `drafter/`, `autolabeler/` and `check-pr/` as sibling actions, `packages/` for the publishable CLI, `dist/` checked in as a build artifact, and `schema.json` for the configuration file. Tooling is split across `biome.jsonc` for formatting, `knip.jsonc`, `.dependency-cruiser.mjs`, a `.licenses/` directory, `mise.toml` and a devcontainer definition.
Configuration templates and further options
The README provides a complete example and an options table, including `change-template`. Key settings include: `template` is the only required key and holds the body, `header` and `footer` bracket it, and `category-template` defaults to `## $TITLE`.
The smallest useful configuration is three lines.
template: |
## What's Changed
$CHANGESFor anything more elaborate the README points at `docs/configuration-loading.md`, which covers loading a generated file, extending another configuration, and loading a configuration from a different repository.
Check PR validates labels without touching the draft release
A second action, Check PR, is described as read-only. It validates a pull request against the title or label conditions in the categories already defined for Release Drafter, so a pull request can be checked against the same rules that will later shape the notes. Its own README is the reference for the workflow, the permissions it needs, the events it responds to, and how matching behaves.
The distinction is the useful part. The drafting action writes to a release and needs `contents: write`; the checking action only reads pull request metadata, which is a much smaller permission to hand to a required status check on every branch.
The tool's own release numbers moved twice within two days
The repository's tags are v7.7.0 from 29 July 2026, v7.8.0 on 1 October 2026 and v7.9.0 on 2 October 2026, and the most recent commit is dated 3 October 2026. Two minor versions in two days is the cadence of a project that publishes on merge rather than on a schedule, and it is a live demonstration of the behaviour the action provides: each merge that resolves a version produces a new draft, and the resolved value is what the tag template prints.
Nothing in the repository documents a release schedule, a support window for older major versions, or a changelog file, so the tag list is the record of what shipped and when.
Editorial conclusion
Release Drafter can assemble release notes and resolve version increments from configurable change categories. Categories can match labels, conventional commit information or paths; an unconditional changelog category can collect otherwise uncategorized changes. Review the configuration against your repository's workflow and permissions. The workspace's Node and npm engine requirements apply when developing or building it; consult the action documentation and test the pinned version in your CI environment.
Frequently asked questions
What does release-drafter actually do?
It keeps a draft release up to date as pull requests merge into a branch, adding each merged change to the draft under a category you configure. It can also resolve the next version number from labels, exclude a merge from the notes with a pre-exclude rule, and template the draft name, the tag, the header, the footer and each category heading.
Does release-drafter need the repository checked out?
No. The action loads its configuration from .github/release-drafter.yml through the GitHub API, so the example workflow has no checkout step at all. A separate configuration-loading document covers loading a generated file, extending another configuration, or loading one from another repository.
Can release-drafter run outside GitHub Actions?
Yes. The release-drafter package provides a command-line interface and a programmatic API for other CI systems, and it supports GitHub, GitHub Enterprise Server, Gitea, Forgejo and GitLab. Installation and API examples live in the package README under packages/release-drafter.
How does release-drafter decide the next version number?
Two ways at once. A category can carry semver-increment, as the Features category does with minor for merges labelled feature or enhancement, and separate version-resolver entries can set the increment from a label, such as major for a merge labelled major or patch by default. The name-template and tag-template then print the resolved value, while version-template, by default $MAJOR.$MINOR.$PATCH$PRERELEASE, covers projects outside Semantic Versioning.
What does the Check PR action from release-drafter do?
It is read-only and validates a pull request against the title or label conditions in your Release Drafter categories, so the same rules that shape the notes can gate a pull request. Its workflow, permissions, supported events and matching behaviour are described in check-pr/README.md.
Does release-drafter do what release-please does?
The repository says nothing about release-please and makes no comparison. What release-drafter documents is narrower: it maintains a draft release from merged pull requests, groups them by category and resolves a version number from labels, while the tag itself is created outside it.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/release-drafter-release-drafter)Star history chart for your README
[](https://hysenlabs.com/projects/release-drafter-release-drafter)Was this useful?