How to automate semantic versioning with GitHub Actions

As your team grows and your project evolves, having a clear branching and commit strategy becomes critical. Combining this with automated tools like semantic-release can optimize your workflow, especially when aiming for regular releases. In this tutorial, we'll set up a strategy for a Next.js project hosted on Amplify, targeting weekly releases.

1. Setting Up Your Development Environment

Ensure that you have a Next.js project initialized and Amplify configured. If not, you can use the Amplify CLI to integrate Amplify with your Next.js project.

2. Define a Branching Strategy

Our strategy involves three main branches:

1. main: This is the stable branch. Code that lands here is ready for production.
2. develop: This is the branch where most of the work happens. New features, bug fixes, and other changes are merged here.
3. feature/*: These are branches for individual features or bug fixes.

Workflow:

• Start a new feature or fix with a new branch: git checkout -b feature/my-new-feature
• Once done, create a pull request to merge feature/my-new-feature into develop.
• When ready for a release (e.g., end of the week), merge develop into main.

3. Commit Strategy with Conventional Commits

Use the Conventional Commits specification. Commit messages should look like:

• fix: fix a minor issue - for patches
• feat: introduce a new feature - for minor releases
• feat: introduce a new feature BREAKING CHANGE: breaks something - for major releases

Using a tool like commitizen can make adhering to this format more straightforward.

4. Configuring GitHub Actions for CI/CD with Amplify and Next.js

1. Create a new .yml file in the .github/workflows directory of your project.
2. Set up the workflow to install, build, test, and release:

name: Release
on:
  push:
    branches:
      - develop
      - main
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 14
      - name: Install Dependencies
        run: npm install
      - name: Build Next.js
        run: npm run build
      - name: Run Tests
        run: npm test
      - name: semantic-release
        run: npm run release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. When you push to develop or main, GitHub Actions will automatically handle the building, testing, and releasing.

5. Setting up Amplify with Next.js

Make sure you've installed and configured the Amplify CLI. Then, inside your project:

1. Initialize Amplify

amplify init

1. Follow the on-screen prompts to configure Amplify with your Next.js project.
2. Push your Amplify changes:
   

amplify push

1. For CI/CD, you can use Amplify Console to connect to your GitHub repo. This will ensure that changes get deployed automatically to Amplify whenever there's a push to your repository.

6. Setting Up semantic-release

Install semantic-release:

npm install --save-dev semantic-release

Now, configure it by adding a release section in your package.json:

"release": {
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

7. Version Numbering and Weekly Releases with semantic-release

semantic-release uses your commit messages to determine the version bump:

• fix: prefixed commits trigger patch releases.
• feat: prefixed commits trigger minor releases.
• BREAKING CHANGE: in the body or footer trigger major releases.

For weekly releases:

1. Ensure all commits follow the Conventional Commits style.
2. At the end of the week, when ready to release, merge develop into main.
3. semantic-release analyzes the commits, decides the version bump, generates a changelog, tags the release, and publishes it.

For visibility, consider adding a CHANGELOG.md to your repository. With semantic-release, it will auto-update with each release.

Weekly Release Cycle:

1. Consistent Release Day: Choose a consistent day, e.g., every Friday. This sets clear expectations.
2. Staging Environment: Merge changes into a staging environment for last-minute testing.
3. Plan for Major Changes: Inform your team and stakeholders in advance if a significant refactoring or breaking change is coming.

Conclusion

With the above setup:

1. New features and fixes get merged into develop.
2. develop gets merged into main for releases, which semantic-release then handles automatically, considering the commit messages.
3. Release notes, changelogs, and version bumps are automatically handled, ensuring a smooth weekly release cycle for your Amplify-hosted Next.js project.

Following this comprehensive guide ensures that your releases are predictable, well-documented, and aligned with industry standards.

• Share
• Tweet