draftsman

draftsman

CLI tool that generates release notes from Conventional Commits, maintaining a continuously-updated draft release across GitHub, GitLab, Gitea, and Forgejo

✨ Features

• Conventional Commits parsing — one changelog entry per commit, no PR metadata required, so it works identically for squash-merge, rebase-merge, and direct-push workflows.
• Continuous draft releases — a live draft release is upserted on every push to the default branch (mirroring Release Drafter's model), finalized later via draftsman publish or the backend's own UI.
• Multi-backend — GitHub, GitLab, Gitea, and Forgejo behind one common interface; switch backend with a single flag.
• PR reference enrichment — best-effort PR linkage extracted from commit-message text (squash-merge trailers), with a live API fallback on GitHub where it's reliable.
• Monorepo aware — map changed file paths to named Packages, each with its own changelog section (single mode) or its own independent Draft Release, version, and tag (multi mode).
• Automatic SemVer — the next version is computed from the Conventional Commit types in range (breaking → major, feat → minor, fix/other → patch); override it explicitly when needed.
• Zero required config — sensible built-in defaults (category mapping, template, tag format) mean draftsman preview works in any repo with no .draftsman.yml at all.
• Configurable — category → section mapping, changelog template, tag format, and the skip-changelog trailer key are all overridable per repo.
• Ships as a GitHub composite Action — no separate install step needed in a GitHub Actions workflow.

🚀 Quick Start

# Nix
nix run github:brpaz/draftsman -- --help

# Go
go install github.com/brpaz/draftsman/cmd/draftsman@latest

# Docker
docker run --rm -v "$(pwd):/repo" -w /repo ghcr.io/brpaz/draftsman:latest preview

Requires git on PATH; a backend API token is only needed for draft/publish, not preview.

Prebuilt binaries, prerequisites, and every install method in full: Installation.

🔌 Provider setup

GitHub, GitLab, Gitea, and Forgejo all work behind one common --backend flag. Token setup, --base-url, and CI examples per provider: Provider setup.

Usage

GitHub Action

A composite Action (action.yml at the repo root) wraps the CLI so a workflow can uses: it directly instead of hand-installing the binary.

Keep the draft release up to date on every push to the default branch:

name: Update draft release

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  draft:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # full history — draftsman walks commits since the last tag
      - uses: brpaz/draftsman@v1
        with:
          command: draft
          backend: github
          token: ${{ secrets.GITHUB_TOKEN }}

Publish the draft on demand:

name: Publish release

on:
  workflow_dispatch:
    inputs:
      version:
        description: "Override the auto-computed version (optional)"
        required: false

permissions:
  contents: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: brpaz/draftsman@v1
        with:
          command: publish
          backend: github
          token: ${{ secrets.GITHUB_TOKEN }}
          version: ${{ inputs.version }}

--repo needs no input — it's read from the GITHUB_REPOSITORY environment variable GitHub Actions already sets on every runner.

For GitLab CI, Gitea Actions, and Forgejo Actions workflow examples (no composite Action exists for those — the binary/Docker image is used directly), see the provider guides linked above.

CLI

Three commands, all reading the current directory as the git repo:

draftsman preview
draftsman draft --backend github --token "$GITHUB_TOKEN" --repo owner/repo
draftsman publish --backend github --token "$GITHUB_TOKEN" --repo owner/repo --version 1.2.0

Full flag reference (including env var equivalents, --package, and multi-mode behavior): CLI reference.

Configuration

An optional .draftsman.yml at the repo root overrides any built-in default — every field is optional:

mode: multi # single (default) | multi

categories:
  - type: feat
    section: Features
  - type: fix
    section: Bug Fixes

packages:
  - path: packages/api
    name: API
  - path: packages/web
    name: Web

skip-changelog-trailer: Skip-Changelog
tag-format: "{{package}}/v{{version}}"

Full field reference and the built-in default template: Configuration.

📚 Documentation

Full documentation, including architecture and design decisions, lives under docs/ and is published as a static site at brpaz.github.io/draftsman (built with Zensical):

• Installation — prerequisites and every install method in detail.
• Configuration — full .draftsman.yml reference.
• CLI reference — every command, flag, and environment variable.
• Provider setup — GitHub, GitLab, Gitea, Forgejo: tokens, --base-url, CI examples.
• Git Workflows — trunk-based, GitHub Flow, Git Flow.
• Development — environment setup, architecture, and the ADRs behind PR linkage, the continuous-draft model, commit-based entries, single vs multi release mode, and GitLab's upcoming-release-as-draft approximation.

Coming from release-drafter? See the migration guide, or let an agent do the translation — a Claude Code skill is included:

npx skills add brpaz/draftsman --skill migrate-from-release-drafter --agent claude-code

🤝 Contributing

All contributions are welcome. Please check CONTRIBUTING.md for details.

🫶 Support

If you find this project helpful and would like to support its development, there are a few ways you can contribute:

👱 Contributors

• Bruno Paz - Creator and maintainer

❤️ Acknowledgements

📃 License

Distributed under the MIT License. See LICENSE file for details.

📩 Contact

• 📧 Email: bruno@brunopaz.dev
• 🐞 Issues: GitHub Issues
• 🖇️ Source: https://github.com/brpaz/draftsman