Drafts your next release notes as pull requests are merged into your branch(es).

`. `0` always collapses, `-1` disables collapsing. Defaults to `-1`. | | `semver-increment` | `changelog`, `version-resolver` | Version increment contributed by matching changes. Can be `major`, `minor`, or `patch`. Defaults to `patch`. Ignored for `pre-include` and `pre-exclude`. | Each category can define a `when` condition as either: - a single condition object - an array of condition objects, where matching any one condition is enough Within one condition, conventional commit, label, and path predicates are combined with AND logic. The condition keys are: | Key | Description | | -------------- | ------------------------------------------------------------------------------ | | `conventional` | Conventional commit predicates to compare against the change title or message. | | `label` | Shorthand for one `labels` entry. | | `labels` | Label predicates to compare against the pull request labels. | | `labels-mode` | How the configured labels are matched. Defaults to `any`. | | `path` | Shorthand for one `paths` entry. | | `paths` | Glob patterns to compare against the files changed by the change. | | `paths-mode` | How the configured paths are matched. Defaults to `any`. | ```yml categories: - title: '🚀 Features' semver-increment: 'minor' when: - conventional: type: 'feat' - labels: - 'feature' - 'enhancement' - title: '🐛 Bug Fixes' when: - labels: - 'bug' - 'fix' - labels: - 'regression' paths: - 'src/**' - title: '⬆️ Dependencies' collapse-after: 0 exclusive: true when: label: 'dependencies' - type: 'pre-exclude' when: label: 'skip-changelog' ``` The `labels-mode` and `paths-mode` options control how the configured labels or path patterns are compared. `any` is the default. Path matching operates on the pull request's changed files. The `conventional` option parses the pull request title as a conventional commit header. Set it to `true` to match any conventional title, or configure `type`/`types`, `scope`/`scopes`, and `breaking`: ```yml categories: - title: 'Conventional Changes' when: conventional: true - title: '🚀 Features' semver-increment: 'minor' when: conventional: type: 'feat' - title: '💥 Breaking API Changes' semver-increment: 'major' when: conventional: type: 'feat' scope: 'api' breaking: true ``` Within a condition, `label` is shorthand for a single `labels` entry. If both `label` and `labels` are present, they are combined before `labels-mode` is applied. With the default `labels-mode: any`, `labels: ["feature", "enhancement"]` matches pull requests carrying either label. Likewise, `path` is shorthand for a single `paths` entry. If both `path` and `paths` are present, they are combined before `paths-mode` is applied. The available matching modes are: - `any`: at least one configured value matches - `all`: every configured value matches - `only`: every change value is included in the configured set - `exactly`: the change values and configured values are the same set If a condition does not configure any `label`/`labels` or `path`/`paths`, the corresponding `*-mode` setting has no effect. An omitted or empty `when` matches all changes, but the meaning depends on the category type: - at most one `type: changelog` category may omit `when`; it becomes the bucket for otherwise uncategorized changes - a `type: version-resolver` category with no `when` acts as the fallback when no other version-resolver category matches - `pre-include` and `pre-exclude` categories with no `when` match every change Changes with matching labels or paths will now be grouped together: Adding such labels to your PRs can be automated by using the embedded [Autolabeler action](#autolabeler). Optionally you can add a `collapse-after` entry to your category item, if the category has more than the defined `collapse-after` pull requests then it will show all pull requests collapsed for that category. Setting `collapse-after` to `0` will always collapse the category regardless of the number of pull requests, and setting it to `-1` disables collapsing. Append the `collapse-after` integer to your category as following: ```yml categories: - title: '⬆️ Dependencies' collapse-after: 3 when: label: 'dependencies' ``` ## Exclude Changes The recommended way to exclude changes is a `type: pre-exclude` category. For example, append the following to your `.github/release-drafter.yml` file: ```yml categories: - type: 'pre-exclude' when: label: 'skip-changelog' ``` Changes with the label "skip-changelog" will now be excluded from the release draft. ## Include Changes The recommended way to include only a subset of changes is a `type: pre-include` category. Only changes that match at least one `pre-include` category are kept for the rest of the pipeline. For example, append the following to your `.github/release-drafter.yml` file: ```yml categories: - type: 'pre-include' when: labels: - 'app-foo' ``` Changes with the label "app-foo" will be the only changes included in the release draft. ## Exclude Contributors By default, the `$CONTRIBUTORS` variable will contain the names or usernames of all the contributors of a release. The `exclude-contributors` option allows you to remove certain usernames from that list. This can be useful if don't wish to include yourself, to better highlight only the third-party contributions. ```yml exclude-contributors: - 'myusername' ``` ## Replacers You can search and replace content in the generated changelog body, using regular expressions, with the `replacers` option. Each replacer is applied in order. ```yml replacers: - search: '/CVE-(\d{4})-(\d+)/g' replace: 'https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-$1-$2' - search: 'myname' replace: 'My Name' - search: '/- ([a-z])/g' replace: '- \u$1' # Uppercase the first letter of each changelog entry ``` `search` will be parsed to a RegExp, and `replace` supports substitution in the [same flavour VSCode does](https://code.visualstudio.com/docs/editing/codebasics#_case-changing-in-regex-replace). ## Autolabeler You can add automatically a label into a pull request, with the `autolabeler` action. ```yaml name: Auto Label on: pull_request: # Only following types are handled by the action, but one can default to all as well types: [opened, reopened, synchronize] # pull_request_target event is required for autolabeler to support PRs from forks # pull_request_target: # types: [opened, reopened, synchronize] permissions: contents: read jobs: auto_label: permissions: pull-requests: write runs-on: ubuntu-latest steps: # runs autolabeler - uses: release-drafter/release-drafter/autolabeler@v7 ``` Available matchers are `files` (glob), `branch` (regex), `title` (regex) and `body` (regex). Matchers are evaluated independently; the label will be set if at least one of the matchers meets the criteria. ```yml # .github/release-drafter.yml autolabeler: - label: 'chore' files: - '*.md' branch: - '/docs{0,1}\/.+/' - label: 'bug' branch: - '/fix\/.+/' title: - '/fix/i' - label: 'enhancement' branch: - '/feature\/.+/' body: - '/JIRA-[0-9]{1,4}/' # ... rest of release-drafter config ``` ## Prerelease workflow Release draft supports working with prereleases. It expects your workflow to be : - A stable release is published, ex: `v3.5.0` - You merge or add meaningful changes your users may want to see, but you are not quite ready for production - You publish a prerelease, ex: `v3.5.0-rc.1` - You merge more changes - You publish another prerelease, ex: `v3.5.0-rc.2` - You decide code is ready for production, you publish `v3.5.1` (or another increment based on your changes) With release-drafter, you can draft each of these releases and prereleases with the appropriate content using parameter '`prerelease`' and '`prerelease-identifier`' - available as either an input of from the config-file. ```yaml jobs: update_full_release_draft: runs-on: ubuntu-latest steps: - uses: release-drafter/release-drafter@v6 with: prerelease: false # the default # ... rest of your config update_prerelease_draft: runs-on: ubuntu-latest steps: - uses: release-drafter/release-drafter@v6 with: prerelease: true prerelease-identifier: 'rc' # Use semver identifiers : alpha, beta, rc, etc ``` Here, both jobs run in parallel every time you add changes to the configured branch. - `update_full_release_draft` will pile-up changes since `v3.5.0` inside a draft for `v3.5.1` (or `v3.6.0` or `v4.0.0`, depending on your config) - `update_prerelease_draft` will pile-up changes since the last prerelease in a prerelease-draft. Changes are : - if no previous (published) prereleases are found - changes since `v3.5.0` in a draft for `v3.5.0-rc.1` (prerelease-draft) - or if `v3.5.0-rc.1` exists (published) already - changes since `v3.5.0-rc.1` in a draft for `v3.5.0-rc.2` (prerelease-draft) Some users like to run `update_prerelease_draft` with `publish: true`, such as prereleases are published immediately without the need for human intervention (or an external automation). Since prereleases are not meant to be stable in the first place, automation may be an acceptable risk for you too. > [!IMPORTANT] > > - `prerelease-identifier` is not required when `prerelease` is enabled, but > your prerelease may not be named after / be associated with a tag that is > semver-compliant to an actual prerelease. > - when specified, `prerelease-identifier` enables `prerelease: true` if both > values come from the same config location; explicit action inputs still take > precedence over config file values If you want your stable releases to include changes since the last prerelease instead of the last stable release, use `include-pre-releases: true`. This can reduce the number of changes included in the stable release body, but diverges from the standard workflow depicted above. ## Projects that don't use Semantic Versioning If your project doesn't follow [Semantic Versioning](https://semver.org) you can still use Release Drafter, but you may want to set the `version-template` option to customize how the `$NEXT_{PATCH,MINOR,MAJOR}_VERSION` environment variables are generated. For example, if your project doesn't use patch version numbers, you can set `version-template` to `$MAJOR.$MINOR`. If the current release is version 1.0, then `$NEXT_MINOR_VERSION` will be `1.1`. ## Action Inputs The Release Drafter GitHub Action accepts a number of optional inputs directly in your workflow configuration. These will typically override default behavior specified in your `release-drafter.yml` config. | Input | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `config-name` | If your workflow requires multiple release-drafter configs it be helpful to override the config-name. The config should still be located inside `.github` as that's where we are looking for config files. | | `token` | Access token used to make requests against the GitHub API. Defaults to `${{ github.token }}` | | `dry-run` | When enabled, no write operations (creating/updating releases or adding labels) are performed. Instead, the action logs what it would have done. Default : `false` | | `name` | The name that will be used in the GitHub release that's created or updated. This will override any `name-template` specified in your `release-drafter.yml` if defined. | | `tag` | The tag name to be associated with the GitHub release that's created or updated. This will override any `tag-template` specified in your `release-drafter.yml` if defined. | | `filter-by-range` | Filter releases that satisfies a semver range. Evaluates the tag name againts node's `semver.satisfies()`. | | `version` | The version to be associated with the GitHub release that's created or updated. This will override any version calculated by the release-drafter. | | `publish` | A boolean indicating whether the release being created or updated should be immediately published. This may be useful if the output of a previous workflow step determines that a new version of your project has been (or will be) released, as with [`salsify/action-detect-and-tag-new-version`](https://github.com/salsify/action-detect-and-tag-new-version). | | `prerelease` | Whether to draft a prerelease, with changes since another prerelease (if applicable). Default `false`. | | `prerelease-identifier` | A string indicating an identifier (alpha, beta, rc, etc), to increment the prerelease version. This automatically enables `prerelease` when both options come from the same config location; explicit action inputs still take precedence. Default `''`. | | `include-pre-releases` | When looking for the last published release to scan changes up-to, include pre-releases. Has no effect if using `prerelease: true` (already enabled). Default `false`. | | `latest` | A string indicating whether the release being created or updated should be marked as latest. | | `commitish` | The release target: a branch, commit SHA, or fully qualified tag or pull request ref. Tag and pull request refs are resolved to commit SHAs. Pull request merge refs force output-only dry-run mode and disable publishing. | | `header` | A string that would be added before the template body. | | `footer` | A string that would be added after the template body. | ## Action Outputs The Release Drafter GitHub Action sets a couple of outputs which can be used as inputs to other Actions in the workflow ([example](https://github.com/actions/upload-release-asset#example-workflow---upload-a-release-asset)). | Output | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The ID of the release that was created or updated. | | `name` | The name of this release. | | `tag_name` | The name of the tag associated with this release. | | `body` | The body of the drafted release, useful if it needs to be included in files. | | `html_url` | The URL users can navigate to in order to view the release. i.e. `https://github.com/octocat/Hello-World/releases/v1.0.0`. | | `upload_url` | The URL for uploading assets to the release, which could be used by GitHub Actions for additional uses, for example the [`@actions/upload-release-asset GitHub Action`](https://www.github.com/actions/upload-release-asset). | | `resolved_version` | Version resolved by [Version Resolver](#version-resolver). i.e. `6.3.1` | | `major_version` | Major part of resolved version by [Version Resolver](#version-resolver). i.e. `6` for version `6.3.1` | | `minor_version` | Minor part of resolved version by [Version Resolver](#version-resolver). i.e. `3` for version `6.3.1` | | `patch_version` | Patch part of resolved version by [Version Resolver](#version-resolver). i.e. `1` for version `6.3.1` | ## GitHub Enterprise Server (GHES) Release Drafter creates its GitHub client with [`@actions/github.getOctokit()`](https://github.com/actions/toolkit/tree/main/packages/github#readme). In GitHub Actions, that client uses the runtime API base URL from `GITHUB_API_URL`, so the same workflow can target GHES without extra `github.com`-specific configuration, assuming the required REST and GraphQL APIs are available on the instance. ## Contributing Third-party contributions are welcome! 🙏🏼 See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for step-by-step instructions. > [!IMPORTANT] > > Before pushing, run `npm run all` to format, lint, type-check, test, and > regenerate all build artifacts. The CI pipeline enforces that no uncommitted > changes remain after these steps. If you need help or have a question, let us know via [a GitHub issue](https://github.com/release-drafter/release-drafter/issues/new).