General

Tag and Release Your Project with GitHub Actions Workflows

Published Aug 11, 2023

Updated Aug 18, 2023

9 min read

Tag and Release your project with GitHub Actions Workflows

GitHub Actions is a powerful automation tool that enables developers to automate various workflows in their repositories. One common use case is to automate the process of tagging and releasing new versions of a project. This ensures that your project's releases are properly versioned, documented, and published in a streamlined manner. In this blog post, we will walk you through two GitHub Actions workflows that can help you achieve this.

Understanding GitHub Tags and Releases

GitHub tags and releases are essential features that help manage and communicate the progress and milestones of a project. Let's take a closer look at what they are, why they are useful, and how they can be used effectively.

GitHub Tags

A GitHub tag is a specific reference point in a repository's history that marks a significant point of development, such as a release or a specific commit. Tags are typically used to identify specific versions of a project. They are lightweight and do not contain any additional metadata by default.

Tags are useful for several reasons:

Versioning: Tags allow you to assign meaningful version numbers to your project, making it easier to track and reference specific releases.
Stability: By tagging stable versions of your project, you can provide users with a reliable and tested codebase.
Collaboration: Tags enable contributors to work on specific versions of the project, ensuring that everyone is on the same page.

GitHub Releases

GitHub releases are a way to package and distribute specific versions of your project to users. A release typically includes the source code, compiled binaries, documentation, and release notes. Releases provide a convenient way for users to access and download specific versions of your project.

Releases offer several benefits:

Communication: Releases allow you to communicate important information about the changes, improvements, and bug fixes included in a specific version.
Distribution: By packaging your project into a release, you make it easier for users to download and use your software.
Documentation: Including release notes in a release helps users understand the changes made in each version and any potential compatibility issues.

Effective Use of Tags and Releases

To make the most of GitHub tags and releases, consider the following tips:

Semantic Versioning: Follow a consistent versioning scheme, such as semantic versioning (e.g., MAJOR.MINOR.PATCH), to clearly communicate the nature of changes in each release.
Release Notes: Provide detailed and concise release notes that highlight the key changes, bug fixes, and new features introduced in each version. This helps users understand the impact of the changes and make informed decisions.
Release Automation: Automate the release process using workflows, like the one described in this blog post, to streamline the creation of tags and releases. This saves time and reduces the chances of human error.

By leveraging GitHub tags and releases effectively, you can enhance collaboration, improve communication, and provide a better experience for users of your project.

The Goal

The idea is to have a GitHub action that, once triggered, updates our project's version, creates a new tag for our repository, and pushes the updates to the main branch. Unfortunately, the main branch is a protected branch, and it's not possible to directly push changes to a protected branch through a GitHub action. Therefore, we need to go through a pull request on the main branch, which, once merged, will apply the changes due to the version update to the main branch.

We had to split the workflow into two different GitHub actions: one that creates a pull request towards the main branch with the necessary code changes to update the repository's version, and another one that creates a new tag and releases the updated main branch. This way, we have one additional click to perform (the one required to merge the PR), but we also have an intermediate step where we can verify that the version update has been carried out correctly.

Let’s dive into these two workflows.

Update version and create Release's PR Workflow

name: Update version and create Release's PR Workflow

on:
	workflow_dispatch:
		inputs:
	    version:
		    description: 'Version name'
		    required: true
		    default: 'minor'
		    type: choice
		    options:
		      - major
		      - minor
		      - patch

jobs:
	version:
	    runs-on: ubuntu-latest
	    steps:
	      - name: Checkout code
	        uses: actions/checkout@v3
	      - name: Setup Node.js
	        uses: actions/setup-node@v3
	        with:
	          node-version: "16.x"
	      - name: Install dependencies
	        run: npm install
		  - name: Set up Git
		    run: |
	          git config user.name "Your GitHub User Name"
	          git config user.email "Your GitHub User Email"
	      - name: Update the version
	        id: update_version
	        run: |
	          echo "version=$(npm version ${{ github.event.inputs.version }} --no-git-				  	tag-version)" >> $GITHUB_OUTPUT
	      - name: Update Changelog
		    id: update_changelog
	        run: |
	          sed -i 's/Unreleased/${{ steps.update_version.outputs.version }}/g'   CHANGELOG.md
	      - name: Create pull request
	        id: create_pr
	        uses: peter-evans/create-pull-request@v5
	        with:
	          token: ${{ secrets.GITHUB_TOKEN }}
	          branch: release/${{ steps.update_version.outputs.version }}
	          title: "Release: ${{ steps.update_version.outputs.version }} Pull Request"
	          body: "This pull request contains the updated package.json with the new   	release version"
	          base: main

Walkthrough:

Step 1: Define the Workflow

The workflow starts with specifying the workflow name and the event that triggers it using the on keyword. In this case, the workflow is triggered manually using the "workflow_dispatch" event, which means it can be run on-demand by a user. Additionally, the workflow accepts an input parameter called "version," which allows the user to specify the type of version bump (major, minor, or patch). The workflow_dispatch event allows the user to set the "version" input when running the workflow.

Step 2: Prepare the Environment

The workflow will run on an Ubuntu environment (ubuntu-latest) using a series of steps under the jobs section. The first job is named "version."

Step 3: Checkout the Code

The workflow starts by checking out the code of the repository using the actions/checkout@v3 action. This step ensures that the workflow has access to the latest codebase before making any modifications.

Step 4: Set up Node.js

Next, the workflow sets up the Node.js environment using the actions/setup-node@v3 action and specifying the Node.js version 16.x. It's essential to use the appropriate Node.js version required by your project to avoid compatibility issues.

Step 5: Install Dependencies

To ensure the project's dependencies are up-to-date, the workflow runs npm install to install the necessary packages as defined in the package.json file.

Step 6: Configure Git

To perform version bump and create a pull request, the workflow configures Git with a user name and email. This allows Git to identify the author when making changes in the repository.

Step 7: Update the Version

The workflow now performs the actual version bump using the npm version command. The new version is determined based on the "version" input provided when running the workflow. The updated version number is stored in an output variable named update_version, which can be referenced later in the workflow.

Step 8: Update the Changelog

After bumping the version, the workflow updates the CHANGELOG.md file to reflect the new release version. It replaces the placeholder "Unreleased" with the updated version using the sed command. [We will return to this step later]

Step 9: Create a Pull Request

Finally, the workflow creates a pull request using the peter-evans/create-pull-request@v5 action. This action automatically creates a pull request with the changes made in the workflow. The pull request will have a branch name following the pattern "release/", where <version> corresponds to the updated version number.

The outcome of this workflow will be a new open PR in the project with package.json and CHANGELOG.md file changed. [we will speak about the changelog file later]

Now we can check if the changes are good, approve the PR and merge it into main. Merge a PR with a title that starts with "Release:" automatically triggers the second workflow

Tag & Release Workflow

name: Tag and Release Workflow

on:
	pull_request:
	types:
		- closed

jobs:
	release:
	runs-on: ubuntu-latest
	if: startsWith(github.event.pull_request.title, 'Release:')
	steps:
		- name: Checkout code
		uses: actions/checkout@v3
		- name: Setup Node.js
		uses: actions/setup-node@v3
		with:
			node-version: "16.x"
		- name: Install dependencies
		run: npm install
		- name: Build
		run: npm run build
		- name: Set up Git
		run: |
			git config user.name "Yout GitHub User name"
			git config user.email "Your GitHub User email"
		- name: Get tag
		id: get_tag
		run: |
			git branch --show-current
			git pull
			echo "version=v$(npm pkg get version | tr -d '\"')" >> $GITHUB_OUTPUT
		- name: Tag the commit
		run: |
			next_version=${{ steps.get_tag.outputs.version }}
			git tag -a "$next_version" -m "Version $next_version"
			git push --follow-tags
		- name: Create changelog diff
		id: changelog_diff
		run: |
			sed -n "/^## \[${{ steps.get_tag.outputs.version }}\]/,/^## \[$(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1))\]/{/^## \[$(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1))\]/!p;}" CHANGELOG.md > release_notes.md
		- name: Create release
		id: create_release
		uses: actions/create-release@v1
		env:
			GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
		with:
			tag_name: ${{ steps.get_tag.outputs.version }}
			release_name: Release ${{ steps.get_tag.outputs.version }}
			body_path: ./release_notes.md
			draft: false
			prerelease: false
		- name: Delete release_notes file
		run: rm release_notes.md

Walkthrough:

As you can see we added a check for the PR title before starting the job once the PR is merged and closed. Only the PRs with a title that starts with "Release:" will trigger the workflow. The first three steps are the same as the one described in the previous workflow: we check out the code from the repository, we set up node and we install dependencies. Let's start with:

Step 4: Check formatting

To maintain code quality, we run the npm run format:check command to check if the code adheres to the specified formatting rules. This step helps catch any formatting issues before proceeding further.

Step 5: Build

The npm run build command is executed in this step to build the project. This step is particularly useful for projects that require compilation or bundling before deployment.

Step 6: Set up Git

To perform Git operations, such as tagging and pushing changes, we need to configure the Git user's name and email. This step ensures that the correct user information is associated with the Git actions performed later in the workflow.

Step 7: Get tag

In this step, we retrieve the current version of the project from the package.json file. The version is then stored in an output variable called get_tag.outputs.version for later use.

Step 8: Tag the commit

Using the version obtained in the previous step, we create a Git tag for the commit. The tag is annotated with a message indicating the version number. Finally, we push the tag and associated changes to the repository.

Step 9: Create changelog diff

To generate release notes, we extract the relevant changelog entries from the CHANGELOG.md file.

This step helps summarize the changes made since the previous release. (We will return to this step later)

Step 10: Create release

Using the actions/create-release action, we create a new release on GitHub. The release is associated with the tag created in the previous step, and the release notes are provided in the body of the release.

Step 11: Delete release_notes file

Finally, we delete the temporary release_notes.md file created in Step 9. This step helps keep the repository clean and organized.

Once also the second workflow is finished our project is tagged and the new release has been created.

The "Changelog Steps"

As you can see the release notes are automatically filled, with a detailed description of what has been added, fixed, or updated in the project.

This was made possible thanks to the "Changelog steps" in our workflows, but to use them correctly, we need to pay attention to a couple of things while developing our project.

Firstly, to the format of the CHANGELOG.md file. This will be our generic template:

But the most important aspect, in addition to keeping the file up to date during developments by adding the news or improvements we are making to the code under their respective sections, is that every time we start working on a new project release, we begin the paragraph with ## [Unreleased].

This is because, in the first workflow, the step related to the changelog will replace the word "Unreleased" with the newly created project version. In the subsequent workflow, we will create a temporary file (which will then be deleted in the latest step of the workflow), where we will extract the part of the changelog file related to the new version and populate the release notes with it.

Conclusion

Following these Tag and Release Workflows, you can automate the process of creating releases for your GitHub projects. This workflow saves time, ensures consistency, and improves collaboration among team members. Remember to customize the workflow to fit your project's specific requirements and enjoy the benefits of streamlined release management.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Mattia Magi

How to Retry Failed Steps in GitHub Action Workflows

Sometimes things can go wrong in your GitHub Action workflow step(s), and you may want to retry them. In this article, we'll cover two methods for doing this! Pre-requisites - Git This should be installed in your path. - GitHub account: We'll need this to use GitHub Actions. Initial setup In order to follow along, here are the steps you can take to setup your GitHub Actions workflow: Initialize your git repository In your terminal, run git init to create an empty git repository or skip this step if you already have an existing git repository. Create a workflow file GitHub workflow files are usually .yaml/.yml files that contain a series of jobs and steps to be executed by GitHub Actions. These files often reside in .github/workflows. If the directories do not exist, go ahead and create them. Create a file retry.yml in .github/workflows. For now, the file can contain the following: ` Testing your workflow You can test your GitHub Action workflow by pushing your changes to GitHub and going to the actions tab of the repository. You can also choose to test locally using Act. Retrying failed steps Approach 1: Using the retry-step action By using the retry-step action, we can retry any failed shell commands. If our step or series of steps are shell commands, we can use the retry-step action to retry them. > If, however, you'd like to try retry a step that is using another action, then the retry-step action will NOT work for you. In that case, you may want to try the alternative steps mentioned below. Modify your action file to contain the following: ` Approach 2: Duplicate steps If you are trying to retry steps that use other actions, the retry-step action may not get the job done. In this case, you can still retry steps by retrying steps conditionally, depending on whether or not a step failed. GitHub provides us with two main additional attributes in our steps: - continue-on-error - Setting this to true means that the even if the current step fails, the job will continue on to the next one (by default failure stops a job's running). - steps.{id}.outcome - where {id} is an id you add to the steps you want to retry. This can be used to tell whether a step failed or not, potential values include 'failure' and 'success'. - if - allows us to conditionally run a step ` Bonus: Retrying multiple steps If you want to retry multiple steps at once, then you can use composite actions to group the steps you want to retry, and then use the duplicate steps approach mentioned above. Conclusion How do you decide which approach to use? - If you are retrying a step that is only shell commands, then you can use the retry step action. - If you are retrying a step that needs to use another action, then you can use duplication of steps with conditional running to manually retry the steps....

Nov 29, 2022

3 mins

GitHub Actions

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

Introduction In the world of software development, GitHub workflows are crucial for automating CI/CD processes. However, a key challenge emerges when these workflows report a 'success' despite underlying issues, like failed tests. This is especially common in scenarios involving tests (e.g., Cypress) and notifications (e.g., Slack) within the same workflow. This blog post aims to highlight the importance of accurate GitHub workflow statuses for better visibility and team response, and how to ensure your workflows reflect the true outcome of their runs. The Problem with Misleading Workflow Statuses Consider a scenario in a GitHub workflow where end-to-end tests are run using Cypress. ` If these tests fail, but the workflow proceeds to a subsequent step, like sending a notification via Slack, which completes successfully, the entire workflow might still show a green checkmark. This misleading success status suggests everything is functioning as intended, when in fact, there could be significant underlying issues. The core issue is the determination of workflow success. Even if critical steps like testing fail, later steps without errors can override this, resulting in a false sense of security. This not only delays bug detection but can also lead to faulty code advancing in the CI/CD pipeline. It's crucial for the overall workflow status to accurately reflect failures in critical steps to ensure prompt and appropriate responses to issues. Crafting a Solution and Best Practices Ensuring Accurate Status Reporting To address the issue of misleading workflow statuses, it’s essential to configure your GitHub Actions properly. The goal is to ensure that the workflow accurately reflects the success or failure of critical tasks, such as running tests, regardless of the success of subsequent steps. Adjusting the Workflow Conditional Notifications: First, set up notifications to execute conditionally based on the outcome of critical steps. This ensures you're alerted of the workflow status without altering the overall result. For example, sending a Slack message if a Cypress test fails: ` Explicit Failure Handling: After configuring conditional notifications, explicitly handle failure scenarios. If a critical step like a Cypress test fails, force the workflow to exit with a failure status. This step is crucial to ensure that the overall workflow reflects the true status: ` Best Practices: Clear Step Separation: Clearly separate and label each step in your workflow for easier readability and troubleshooting. Regular Reviews: Periodically review your workflows to ensure they are aligned with the latest project requirements and best practices. Document Workflow Logic: Maintain documentation for your workflows, especially for complex ones, to aid in understanding and future modifications. By first setting up conditional notifications and then enforcing explicit failure handling, you maintain both alertness to issues and accuracy in workflow status. This approach ensures that failures in critical steps like tests are not overshadowed by subsequent successful steps, keeping the reported status of your workflow true to its actual state. Conclusion Accurate GitHub workflow statuses are vital for a transparent and efficient CI/CD process. By implementing conditional notifications and explicit failure handling, we ensure that our workflows truthfully represent the success or failure of critical tasks. This not only fosters better issue awareness and response but also upholds the integrity of our development practices. Embrace these steps as part of your commitment to maintaining clear and reliable automation processes in your projects. Happy coding!...

Mar 22, 2024

3 mins

GitHubGit

"How do I undo my most recent commit?" - Mastering the git reset command

"How do I undo my most recent commit?" - Mastering the git reset command Git is a powerful version control system, but even experienced developers sometimes make mistakes. Whether you've committed changes to the wrong branch, made a typo in your commit message, or simply want to undo recent changes, the git reset command is your go-to solution. In this post, we'll explore how to use git reset to manage your commit history effectively. The Basics of git reset At its core, git reset moves the HEAD and current branch pointer to a specified commit, effectively "resetting" your working directory to a previous state. The basic syntax is: ` Where specifies how to handle changes in the working directory and staging area, and is the commit you want to reset to. Soft vs. Hard Reset: Understanding the Difference Git reset has two main modes: --soft and --hard. Let's explore each: Soft Reset (--soft) A soft reset moves your HEAD to the specified commit but keeps your changes staged. This is useful when you want to undo commits but keep the changes for recommitting. Example: ` This command undoes the last commit, keeping the changes staged. You can now make additional changes or recommit with a new message. Hard Reset (--hard) A hard reset is more drastic. It moves your HEAD to the specified commit and discards all changes after that commit. Example: ` This command undoes the last commit and discards all changes. Be cautious with this command, as it can lead to data loss! Specifying a Commit Hash Instead of using relative references like HEAD~1, you can specify an exact commit hash: ` This resets to the commit with hash 1a2b3c4, keeping changes staged. Using HEAD~n Notation The HEAD~n notation allows you to specify how many commits back you want to reset. For example: ` This resets to three commits before the current HEAD, discarding all changes. Reverting Pushed Changes If you've already pushed commits you want to undo, you should use git revert instead of git reset to avoid rewriting public history. However, if you must use git reset on a shared branch, you'll need to force push: ` Be extremely cautious with force pushing, as it can cause issues for other developers. Generic Usage of git reset git reset can also be used to unstage changes: ` This removes file.txt from the staging area without changing its contents. Conclusion The git reset command is a powerful tool for managing your Git history. Whether you're undoing recent commits, unstaging changes, or completely resetting your working directory, understanding the different modes of git reset can help you navigate tricky situations in your Git workflow. Remember to use git reset with caution, especially when working with shared repositories. When in doubt, create a backup branch before performing any reset operations....

Oct 18, 2024

2 mins

Git

Learning Paths for Next.JS Developers with Ankita Kulkarni

In this video, Rob Ocel and co-hosts Tracy Lee, Adam Rackis, and Danny Thompson talk with tech educator Ankita Kulkarni about her journey from engineering leader to full-time educator. Ankita shares insights on teaching Next.js, bridging practical knowledge gaps, and helping developers tackle real-world challenges. They discuss Next.js as a React-based framework, its benefits, and the challenges it presents for beginners. Chapters - Introduction to the Podcast and Guests 00:01 - Meet Ankita Kulkarni, Tech Educator 00:26 - Ankita's Transition to Full-Time Education 01:41 - Teaching Practical Knowledge in Next.js 03:19 - Effective Methods for Teaching Next.js 05:27 - Challenges of Being a Full-Time Educator 07:48 - Balancing Broad and Specific Examples 09:54 - Embracing Mistakes as a Teaching Tool 12:13 - Pair Programming and Mentorship 14:00 - Discussion on Next.js and Framework Adoption 16:48 - Advantages and Challenges of Next.js 18:12 - Choosing the Right Framework for Your Needs 20:35 - Impact of Next.js in React Documentation 22:26 - Learning Paths for New Developers 23:24 - The Rise of Full-Stack Web Development 25:09 - Benefits of Frameworks Abstracting Complexity 26:27 - OpenNext and Deployment Flexibility 28:06 - Ankita's Excitement for New Next.js Features 30:35 - The Future of Next.js Without Vercel 32:16 - Final Thoughts and Where to Find Everyone Online 34:21 Follow Ankita Kulkarni on Social Media Twitter: https://x.com/kulkarniankita9 YouTube: https://www.youtube.com/@kulkarniankita Sponsored by This Dot: thisdot.co...

Nov 12, 2024

2 mins

NextJSJavaScript

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Tag and Release your project with GitHub Actions Workflows

Understanding GitHub Tags and Releases

GitHub Tags

GitHub Releases

Effective Use of Tags and Releases

The Goal

Update version and create Release's PR Workflow

Walkthrough:

Step 1: Define the Workflow

Step 2: Prepare the Environment

Step 3: Checkout the Code

Step 4: Set up Node.js

Step 5: Install Dependencies

Step 6: Configure Git

Step 7: Update the Version

Step 8: Update the Changelog

Step 9: Create a Pull Request

Tag & Release Workflow

Walkthrough:

Step 4: Check formatting

Step 5: Build

Step 6: Set up Git

Step 7: Get tag

Step 8: Tag the commit

Step 9: Create changelog diff

Step 10: Create release

Step 11: Delete release_notes file

The "Changelog Steps"

Conclusion

Mattia Magi

How to Retry Failed Steps in GitHub Action Workflows

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

"How do I undo my most recent commit?" - Mastering the git reset command

Learning Paths for Next.JS Developers with Ankita Kulkarni

Let's innovate together!

How to Retry Failed Steps in GitHub Action Workflows

Ensuring Accurate Workflow Status in GitHub for Enhanced Visibility

"How do I undo my most recent commit?" - Mastering the git reset command

Learning Paths for Next.JS Developers with Ankita Kulkarni