Configuration

Release Planner reads its settings from .release-planner/config.yml. After changing it, run release-planner install and commit the result.

The minimum

Only two settings are required:

schema-version: 1   # the format of this file; always 1 for now
version: v0.3.2     # the Release Planner version this repository uses

Everything else has a sensible default, so many repositories never add more.

Every setting

This example sets everything. The comments say what each setting does and what you get if you leave it out.

# Required. The format of this file. Always 1 for now.
schema-version: 1

# Required. The Release Planner version to use, as a release tag.
# A full commit SHA also works; your workflow then builds Release Planner
# from source with Go instead of downloading a release. Bumping it upgrades the
# GitHub Actions workflow (.github/workflows/release-planner.yml) and the agent
# guide together; run release-planner install after changing it.
version: v0.3.2

# The version your first release must use.
# Default: v0.1.0
first-version: v1.0.0

# Where the release notes files live, one per release.
# Default: _releases
release-notes-dir: _releases

# The branch that release pull requests merge into, and releases are published from.
# Default: main
release-branch: main

# Your own release notes style: the markdown file that holds it, and whether
# it adds to the default style (append) or replaces it (replace).
# Default: none; the agent uses the default style.
release-notes-style:
  file: .release-planner/release-notes-style.md
  mode: append

# Checks to run on the release commit, on the release pull request.
# Default: none.
release-checks:
  run: make smoke-test

# Your workflow that builds the files to attach to each release.
# Default: none; releases have no files.
release-assets:
  workflow: build-release.yml

# Your workflow to run after you merge and before the release is tagged, such as
# one that applies database migrations. Its jobs name the GitHub environment
# that holds its credentials, and Release Planner reads it from there.
# Default: none.
pre-publish:
  - workflow: migrate-database.yml

# Your workflows to run after each new stable release, in this repository or,
# with repository, in another one. Set prereleases: true to run one for
# prereleases too. Default: none.
post-publish:
  - workflow: deploy.yml
  - repository: fabricahq/homebrew-tap
    workflow: update-code-rules.yml

# Release notes rules to turn off, by ID. List them with: release-planner validate --rules
# Default: every rule is on.
release-notes-rules:
  no-long-heading: off

For the details of the last six, see Release notes style, Release checks, Release assets, Pre-publish workflows, Post-publish workflows, and Release notes rules.

Upgrade Release Planner

Install the new version, change version in config.yml to match, then regenerate your files:

curl -fsSL https://raw.githubusercontent.com/fabricahq/release-planner/main/install.sh | sh -s -- --version v0.3.2
release-planner install

One version pin covers everything: the GitHub Actions workflow and the agent’s instructions change together.

v0.5.0 changes what the release-assets workflow must output. If you use release assets, follow Upgrade to v0.5.0 in the same pull request.

Generated files

install writes the GitHub Actions workflow, the agent skill, and the Releases section of AGENTS.md. Don’t edit them. Change the config and run install instead.

• install is safe to run any number of times. It updates files that are out of date and leaves everything else alone.
• Your own text in AGENTS.md is never touched. Release Planner only changes the text between its release-planner:begin and release-planner:end markers.
• If a generated file was edited by hand, install refuses to overwrite it and says why. Move your change into the config, or run install --force to discard it.
• The release workflow runs release-planner check on every release pull request, so an out-of-date or edited file fails before it can cause a bad release.

To stop using Release Planner, run release-planner uninstall. It removes the generated files and the AGENTS.md section, and leaves .release-planner/ and your release notes in place.