Setting up changesets for automated changelog management and releases with GitHub actions

Automating the annoying stuff with the power of Changesets

Changesets is a workflow tool that helps developers with software versioning and automated releases. During software development, contributors can create a changeset with semantic versioning information to represent a set of related changes, such as bug fixes or new features. Each changeset includes a description of the changes and a list of affected packages.

When a new package version is ready to be released, changesets can trigger a release process to merge these entries and automatically generate release notes. With the use of the changesets/changelog-github extension, we can further automate this process by setting up a GitHub actions workflow that always keeps a version release PR up to date. When it is time to release, all we need to do is simply merge this version release PR.

Many popular open source packages are using changesets, such as XState, Emotion, and mobx.

Let’s show you how to setup this awesome workflow 🤖.

—

Installing changesets into your repo

1. In your project, add changesets and setup the config.

> yarn add @changesets/cli @changesets/changelog-github
> yarn changeset init

A .changset folder should be created for us with a README and config.json file. In its default configuration, there are two notable commands:

• yarn changeset — the command to generate a changeset entry
• yarn changeset version — the command to gather changeset entries to create or update the changelog

2. We can now configure the changesets/changelog-github extension to automatically keep a version release PR updated.

We can do this with the following changes to the config.json file:

// For repo name, use "{repo-owner}/{repo-name}"

{
  "changelog": [
    "@changesets/changelog-github",
    { "repo": "chanonroy/example-project" }
  ],
  "baseBranch": "main"
}

3. We now want to create a GitHub action that will create or update the version release PR whenever we make changes to main.

Create a new GitHub actions file called update-release-pr.yml within .github/workflows.

 name: Release

on:
  push:
    branches:
      - main

concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v3

      - name: Setup Node.js 16
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: Install Dependencies
        run: yarn

      - name: Create Release Pull Request
        uses: changesets/action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You will need to setup your workflow permission in GitHub settings to allow the changesets action to read your GITHUB_TOKEN.

With this setup, we are now ready to use changesets 🦋

Let’s explore how we want to use this workflow in two scenarios:

1. The developer flow — for when we want to add changeset entries
2. The release flow — for when we want to make a release

💻 Developer flow: Adding a changeset entry

After a developer makes a contribution to your project, they can use the following command to add a changeset:

> yarn changeset

This will prompt the user to describe their changes with a selection of change scope (patch, minor, major) and a brief text description.

You will notice that a new entry is created with a unique file name in the .changeset folder. The file name slug will be quite goofy, amusing, and completely irrelevant to the actual changeset information.

Yes, this is intended 😂

When we merge our PR with a changeset entry into main, you’ll notice that a GitHub action is ran to create or update our version release PR with changeset entries.

📦 Release flow: Updating the changelog

When are ready to release, all we need to do is simply merge the version release PR, which will then do a few things:

1. Update the version in our package.json file
2. Create or update the changelog with newly released changeset entries
3. Clean up newly released changeset entry files in the .changeset folder

And there it is, a nicely formatted changelog file with references to changeset authors and their pull requests.

🚀 Where to go next

From here, there are a few ways that we can augment our existing functionality:

• 📝 Customizing the title and description of the version release PR.
• 👮 Setting up a CI condition to block pull request merging until a changeset entry is made.
• 📦 Automatically publishing to npm when the version packages PR is configured.