CLI tool
release-drafter/release-drafter avatar
release-drafter/release-drafter

Release Drafter groups merges into categories that also decide the version bump

Drafts your next release notes as pull requests are merged into master.

3,954 stars390 forksTypeScriptISC

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.

From daily snapshots

Star history

  • release-drafter/release-drafter3,954 ★ · +10
Star history
Repository2026-09-262026-11-15
release-drafter/release-drafter3.9k4k

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`.

yaml
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.yml

There 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.

yml
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.

yml
template: |
  ## What's Changed

  $CHANGES

For 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

  1. License: ISC
  2. Project website
  3. README
  4. release-drafter/release-drafter on GitHub
  5. Releases
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/release-drafter-release-drafter.svg)](https://hysenlabs.com/projects/release-drafter-release-drafter)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/release-drafter-release-drafter.svg)](https://hysenlabs.com/projects/release-drafter-release-drafter)

Was this useful?