How to Use Release Changelog Builder GitHub Action

name: "Release Changelog"
on:
  push:
    tags:
      - "v*"

jobs:
  build-changelog:
    name: "Build Changelog"
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout Code"
        uses: actions/checkout@v4

      - name: "Build Changelog"
        id: build_changelog
        uses: mikepenz/release-changelog-builder-action@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fromTag: "v1.0.0"
          toTag: "v1.1.0"

release-changelog-builder

Build release notes and changelogs exactly the way you want.

What is Release Changelog Builder GitHub Action?​

The Release Changelog Builder GitHub Action automates the process of generating detailed release notes and changelogs based on pull requests (PRs) or commits. It allows flexible configurations to suit your project's needs, whether you want to categorize PRs or include custom labels.

How to Provide Configuration via JSON​

You can provide the action’s configuration directly in your YAML file by specifying it as configurationJson. This allows you to fine-tune changelog behavior, such as defining categories and rules for PRs.

with:
  configurationJson: |
    {
      "categories": [
        {
          "title": "## 🚀 Features",
          "labels": ["feature"]
        },
        {
          "title": "## 🐛 Fixes",
          "labels": ["fix"]
        }
      ]
    }

How to Specify Configuration File​

If you prefer storing configurations in a separate JSON file, you can specify its relative path with configuration. This approach helps in managing complex settings for generating changelogs.

with:
  configuration: "path/to/configuration.json"

How to Set the Output File Path​

The outputFile input specifies the file path where the generated changelog will be stored. This is optional but useful if you want to save the changelog locally.

with:
  outputFile: "changelog.md"

How to Define Repository Owner​

The owner input sets the owner of the repository for which the changelog is being generated. It’s useful when dealing with multiple repositories under different owners.

with:
  owner: "mikepenz"

How to Set the Repository Name​

The repo input defines the name of the repository you want to generate the changelog for. It’s a required field when generating changelogs across different repositories.

with:
  repo: "release-changelog-builder-action"

How to Specify Tags for Changelog​

The fromTag and toTag inputs define the range of commits or PRs to consider when building the changelog. These tags represent the start and end points for the changelog generation.

with:
  fromTag: "v1.0.0"
  toTag: "v1.1.0"

How to Include Open PRs​

The includeOpen input allows you to include currently open pull requests in the changelog. This is useful for tracking pending changes.

with:
  includeOpen: true

How to Ignore Pre-releases​

Set ignorePreReleases to true to exclude pre-releases from changelog generation. This is particularly useful when focusing on stable releases.

with:
  ignorePreReleases: true

How to Fetch PRs via Commits​

The fetchViaCommits input allows fetching PRs based on commits between fromTag and toTag. This is especially useful for repositories that use squash merges.

with:
  fetchViaCommits: true

How to Fetch Reviewers​

The fetchReviewers input enables the fetching of reviewers who approved each PR, adding more context to your changelog.

with:
  fetchReviewers: true

How to Use Commit Mode​

If your project does not use pull requests, you can enable COMMIT mode to generate changelogs based on commit messages. This mode treats commits like PRs but has limited access to PR-related data.

with:
  mode: "COMMIT"

Outputs​

Once the changelog is built, you can access several output variables from the action for further use in subsequent steps.

• outputs.changelog: The built release changelog.
• outputs.fromTag: The starting tag for the changelog.
• outputs.toTag: The ending tag for the changelog.
• outputs.commits: The number of commits included in the release.

Example of using the changelog output in a later step:

steps:
  - name: "Use Changelog"
    run: echo "${{ steps.build_changelog.outputs.changelog }}"