Auto Versioning and Release Notes with GitHub Actions

Keeping track of software versions and generating release notes can be time-consuming and error-prone if done manually. GitHub Actions takes the hassle out of this process by offering automated workflows to manage versioning, generate changelogs, and even complete tagging, building, and publishing in one seamless workflow.

If you’ve been looking for a way to simplify release management, this guide will show you how to use GitHub Actions to auto-version your software, create release notes, and generate changelogs automatically. You’ll also learn how to combine these steps into a single automated pipeline.

By the end of this tutorial, you’ll be able to:

• Use GitHub Actions like actions/create-release and actions/checkout effectively.
• Implement auto-incrementing semantic versioning.
• Automatically generate changelogs from commits.
• Tag, build, and publish artifacts in one cohesive workflow.

Table of Contents

1. Why Automate Versioning and Releases?
2. Using actions/create-release and actions/checkout
3. Semantic Versioning with Auto-Increment
4. Generating Changelogs from Commits
5. Tagging, Building, and Publishing in One Workflow
6. Summary

Why Automate Versioning and Releases?

Manually managing software versions and creating release notes is both inefficient and error-prone, especially in collaborative projects. Automation eliminates these risks by:

1. Reducing Manual Errors: Automated workflows ensure accurate versioning and comprehensive release notes every time.
2. Saving Time: Focus on writing code rather than manually updating changelogs or bumping version numbers.
3. Ensuring Consistency: Automation maintains standard practices, such as semantic versioning, across all releases.
4. Streamlining CI/CD Pipelines: Integrating versioning into your deployment workflow simplifies much of the release process.

Efficient release management keeps developers productive and ensures your users consistently receive high-quality updates.

Using actions/create-release and actions/checkout

GitHub Actions provides a variety of ready-to-use actions to streamline your workflows. For release management, actions/create-release and actions/checkout are key components.

Setting Up actions/checkout

The actions/checkout action is a prerequisite for most workflows. It checks out your repository’s code into the runner, enabling other steps to access and interact with your project files.

Here’s how to include it in your workflow:

steps:
  - name: Checkout code
    uses: actions/checkout@v3

This step ensures your workflow has access to the code’s latest state for building, tagging, or other operations.

Using actions/create-release

Once your code is ready, you can use actions/create-release to create a release in your repository. It simplifies the process of tagging a commit and generating release artifacts.

Below is an example workflow:

steps:
  - name: Create GitHub Release
    uses: actions/create-release@v1
    with:
      tag_name: ${{ github.ref_name }}
      release_name: "Release ${{ github.ref_name }}"
      body: "Automatic release generated through GitHub Actions"
      draft: false
      prerelease: false
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This action does the following:

1. Creates a release with the specified tag name.
2. Generates release notes with a customizable body.
3. Publishes the release (you can also set it as a draft or prerelease).

Together, actions/checkout and actions/create-release form the foundation for automated release pipelines.

Semantic Versioning with Auto-Increment

Semantic versioning (1.0.0) is a widely accepted standard in the software world. Automating version increments ensures consistency while simplifying the release process.

What is Semantic Versioning?

Semantic versioning assigns version numbers in the format MAJOR.MINOR.PATCH, where:

• MAJOR: Incremented for backward-incompatible changes.
• MINOR: Incremented for new features that don’t break existing functionality.
• PATCH: Incremented for small fixes or updates.

For instance:

• 1.0.0 represents the first stable release.
• 1.1.0 adds new features but maintains backward compatibility.
• 1.1.1 fixes bugs without introducing major changes.

Automating Version Increment

You can use tools like semantic-release or custom scripts to auto-increment versions based on commit messages. Here’s how to implement it using GitHub Actions:

steps:
  - name: Bump version
    id: version
    run: |
      git fetch --tags
      CURRENT_VERSION=$(git describe --tags --abbrev=0)
      NEW_VERSION=$(echo $CURRENT_VERSION | awk -F. '{$NF+=1; OFS="."} {print $0}')
      echo "New version is $NEW_VERSION"
      echo "version=$NEW_VERSION" >> $GITHUB_ENV

This script fetches the latest tag, increments the version (e.g., from 1.0.0 to 1.0.1), and stores it in an environment variable for use in subsequent steps.

Generating Changelogs from Commits

A changelog summarizes the changes made in each release, providing users clear visibility into new features, bug fixes, or updates.

Using git log for Changelog Generation

You can use git log to extract commit messages and format them into a changelog. Below is a sample workflow step:

steps:
  - name: Generate Changelog
    id: changelog
    run: |
      git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s" > changelog.md

This step:

1. Compares commits made since the last tag.
2. Outputs a formatted list of commit messages to changelog.md.

Publishing the Changelog

You can include the changelog as part of your release notes using actions/create-release:

steps:
  - name: Append Changelog to Release
    run: |
      body=$(cat changelog.md)
      echo "release_body=$body" >> $GITHUB_ENV
      echo $body
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Including automatically generated changelogs helps keep users up-to-date with minimal effort.

Tagging, Building, and Publishing in One Workflow

Combining these steps into a single cohesive workflow ensures that tagging, building, and publishing happen seamlessly.

Complete Example Workflow

Here’s how to integrate everything into a single GitHub Actions workflow:

name: Auto Versioning and Release

on:
  push:
    branches:
      - main

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

      - name: Bump Version
        id: version
        run: |
          git fetch --tags
          CURRENT_VERSION=$(git describe --tags --abbrev=0)
          NEW_VERSION=$(echo $CURRENT_VERSION | awk -F. '{$NF+=1; OFS="."} {print $0}')
          echo "New version is $NEW_VERSION"
          echo "version=$NEW_VERSION" >> $GITHUB_ENV

      - name: Generate Changelog
        id: changelog
        run: |
          git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s" > changelog.md

      - name: Create Release
        uses: actions/create-release@v1
        with:
          tag_name: ${{ env.version }}
          release_name: "Release ${{ env.version }}"
          body_path: changelog.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Workflow Breakdown

1. Checkout Code ensures your repository is available for further steps.
2. Bump Version auto-increments the version number based on semantic rules.
3. Generate Changelog creates a new changelog for the release.
4. Create Release tags the new version, publishes the changelog, and creates a release on GitHub.

Summary

Automating versioning and release notes with GitHub Actions allows you to streamline your workflows and focus on writing code. To recap:

• Use actions/checkout and actions/create-release for foundational tasks.
• Implement semantic versioning to ensure consistent version increments.
• Generate changelogs automatically from commit messages for transparent release notes.
• Combine tagging, building, and publishing in one workflow to save time.

By following this guide, you’ll have a robust, automated pipeline that reduces effort, mitigates errors, and keeps your project moving forward efficiently. Start automating today and level up your release management process!