How to Create a Draft Release With Notes in GitHub Actions

A draft release lets you review auto-generated notes before they go public, instead of publishing blind.

On a tag push, call gh release create with --draft and --generate-notes so GitHub drafts the changelog from merged PRs.

Steps

• Trigger on tag pushes matching v*.
• Grant contents: write permission.
• Run gh release create with --draft and --generate-notes.
• Review and publish the draft manually.

Workflow

on:
  push:
    tags: ['v*']
permissions:
  contents: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release create "${{ github.ref_name }}" --draft --generate-notes

Gotchas

• Auto-generated notes are built from merged PRs, so good PR titles make good notes.
• A draft is not visible to users until you publish it.
• Latchkey runs release jobs on cheaper runners that retry transient API errors so a release is never half-created.

Related guides