go-semver-release

README

Go Semver Release

Go program designed to automate versioning of Git repository by analyzing their formatted commit history and tagging them with the right semver number. This program can be used directly via its CLI or its corresponding GitHub Action.

• Motivation
• Install
• Usage
• Github Actions
• Release Rules

Motivation

This project was built to create a lightweight and simple tool to seamlessly automate versioning on your Git repository. Following the UNIX philosophy of "make each program do one thing well", it only handles publishing semver tags to your Git repository, no package publishing or any other features.

The Docker image merely weight 7MB and the Go program inside will compute your semver tag in seconds, no matter the size of your commit history.

To use this tool, all you have to do is:

• Choose a release branch (e.g., main)

• Take care to format commits on that branch by following the Conventional Commit convention, which many IDEs plugins offers to do seamlessly (e.g., VSCode, IntelliJ)

[!IMPORTANT] go-semver-release can only read annotated Git tags, so if you plan on only using it in dry-run mode to then use its output to tag your repository with an other action, make sure the tag you are pushing is annotated, otherwise the program will not be able to detect it during its next execution.

Install

If Go is installed on your machine, you can install from source using go install:

$ go install github.com/s0ders/go-semver-release@latest
$ go-semver-release --help

For cross-platform compatibility, you can use the generated Docker image:

$ docker pull soders/go-semver-release:latest
$ docker run --rm soders/go-semver-release --help

For security purposes, each Docker image comes with a corresponding SBOM.

Prerequisites

• The commits of the Git repository to version must follow the Conventional Commit convention.
• The Git repository must already be initialized (i.e., Git HEAD does not point to nothing)

Usage

The CLI supports two mode of execution: remote and local.

In remote mode, the program will attempt to clone the remote repository using the provided URL and access token to then compute the next semver, tag it onto the cloned repository and push it back to the remote.

In local mode, the program takes the path of the already present Git repository, computes the next semver, tags the local repository with it and stops. This mode is a good option security-wise since it lets you use the program without having to configure any kind of right management because it does not require any access token.

Remote mode example:

$ go-semver-release remote --git-url <URL> --rules-path <PATH> --token <TOKEN> \
                           --tag-prefix <PREFIX> --release-branch <NAME> --dry-run --verbose

Local mode example:

$ go-semver-release local <REPOSITORY_PATH> --rules-path <PATH> --tag-prefix <PREFIX> \
                                            --release-branch <NAME> --dry-run --verbose

[!TIP] You can change your tag prefix during the lifetime of your repository (e.g., going from none to v) and this will not affect your semver tags history, meaning that the program will still be able to recognize semver tags made with your old-prefixes, if any. There are no limitation to how many time you can change your tag prefix during the lifetime of your repository.

For more informations about commands and flags usage as well as the default value, simply run:

$ go-semver-release <COMMAND> --help

GitHub Actions

Inputs

The action takes the same parameters as those defined in the usage section. Note that the boolean flags (e.g., --dry-run, --verbose) need to be passed as a string inside your YAML work-flow due to how Github Actions works.

Outputs

The action generate a two outputs

• SEMVER, the computed semver or the current one if no new were computed, prefixed with the given tag-prefix if any;
• NEW_RELEASE, whether a new semver was computed or not.

Release Rules

Release rules define which commit type will trigger a release, and what type of release (i.e. major, minor, patch). By default, the program applies the following release rules:

{
    "rules": [
        {"type": "feat", "release": "minor"},
        {"type": "perf", "release": "minor"},
        {"type": "fix", "release": "patch"}
    ]
}

You can define custom release rules to suit your needs using a JSON or YAML file and by passing it to the program as bellow. Be careful with release rules though, especially major ones, as their misuse might easily make you loose the benefits of using a semantic version number.

rules:
  - type: feat
    release: minor
  - type: perf
    release: patch
  - type: fix
  	release: patch

If a commit type (e.g., chore) is not specified in you rule file, it won't trigger any kind of release.

The following type are supported for release rules: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.

The following release types are supported for release rules: major, minor, patch.