GitHub actions example for automatic release drafts and changelog.md creation

February 28, 2021•3 min read

This post is how to define your release draft via labels in pull requests and the update of the changelog.md after publishing a release

github github actions

What are GitHub actions?

That is well described in this post by Brian Douglas. He has also an entire post series about tips around GitHub actions.

Which problem should be solved?

There are different solutions to create automatic releases based on certain criteria. Again Brian Douglas pointed out some possibilities in this post.

For this open-source project, the requirement was to determine the release structure via labels at the pull request. This was preferred over conventional commits. Also, not every merged pull request should automatically trigger a new release. Therefore, a draft is the right way to collect the changes and publish a version whenever needed.

Addionatylly to the GitHub releases, a changelog.md helps see the version history, for example, directly in the code editor. That changelog.md should be updated every time a release is published.

The combination Release Drafter and gren is the approach to solve the problem.

Configure Release Drafter

To configure Release Drafter in the default way, it needs two files and the according labels.

This template describes the structure of the release draft and the needed labels. The full path is .github/release-drafter.yml

name-template: "v$RESOLVED_VERSION 🌈"
tag-template: "v$RESOLVED_VERSION"
categories:
  - title: "🚀 Features"
    labels:
      - "feature"
      - "enhancement"
  - title: "🐛 Bug Fixes"
    labels:
      - "fix"
      - "bugfix"
      - "bug"
  - title: "🧰 Maintenance"
    label: "chore"
  - title: "🧺 Miscellaneous" #Everything except ABAP
    label: "misc"
change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
version-resolver:
  major:
    labels:
      - "major"
  minor:
    labels:
      - "minor"
  patch:
    labels:
      - "patch"
  default: patch
template: |
  ## Changes
  $CHANGES

The GitHub actions configuration like this:

github/workflows/release-drafter.yml

name: Release Drafter

on:
  push:
    # branches to consider in the event; optional, defaults to all
    branches:
      - main

jobs:
  update_release_draft:
    runs-on: ubuntu-latest
    steps:
      # Drafts your next Release notes as Pull Requests are merged into "master"
      - uses: release-drafter/release-drafter@v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Configure gren

The releases are published manually at certain times. This trigger this configuration.

name: "update changelog"
on:
  release:
    types: [published]

jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Update changelog
        run: |
          npm install github-release-notes
          export GREN_GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
          npm run overrideChangelog
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v3
        with:
          commit-message: update changelog
          title: Update Changelog
          body: Update changelog to reflect release changes
          branch: update-changelog
          base: main

The command "overrideChangelog": "gren changelog --override" from the package.json update then the changelog.md.

Because of the main branch protection, it's not possible to push the changes directly back. This will do this via a pull request with the GitHub action create-pull-request.

How it looks like

The collection of the changes in a release draft.

release-draft

The labels in a pull request.

label-pull-request

The result in the GitHub release.

minor-enhancement

The result in the CHANGELOG.md.

changelog

Code

https://github.com/abap-observability-tools