philipmottershead/semantic-versioning-gitlab repository overview

⁠Semantic Versioning Gitlab

This project provides a gitlab template and Docker image that can be used to automatically version projects using semantic versioning.

Code is a modified version of https://github.com/mrooding/gitlab-semantic-versioning/⁠.

This version adds support for:

• Patch Bumps when pushing into main (23/06/2023)
• Gitlab Templates (01/07/2024)
• Adding configuration as arguements rather than enviroment varibles (01/07/2024)

Visit semver.org⁠ to read more about semantic versioning.

⁠Gitlab component configuation

⁠Minimal Example

include:
  - component: $CI_SERVER_FQDN/Mottershead/ci-cd-templates/semanic-versioning-gitlab/[email protected]
  inputs:
    USERNAME: $GITLAB_USERNAME
    PASSWORD: $GITLAB_PASSWORD

⁠Full configuration example

include:
  - component: $CI_SERVER_FQDN/Mottershead/ci-cd-templates/semanic-versioning-gitlab/[email protected]
  inputs:
    STAGE: version
    USERNAME: $GITLAB_USERNAME
    PASSWORD: $GITLAB_PASSWORD
    BUMP_MINOR_LABEL: bump-minor
    BUMP_MAJOR_LABEL: bump-major
    IMAGE: philipmottershead/semantic-versioning-gitlab
    MAIN_BRANCH_NAME: main
    BRANCH_REGEX: /^release/

⁠Comfiguration

⁠How is the version determined?

Versions are being maintained using git tags.

If no git tag is available, the first version update will result in version 1.0.0. If git tags are available, it will determine whether to do a major, minor, or patch update based on specific merge request labels. The bump-minor and bump-major labels exist to do either a minor or major bump. If a merge request has no labels attached, it will perform a patch update by default.

If pushed directly into main the update the patch version.

⁠Prerequisites

⁠Group labels

As stated above, the version update workflow relies on merge request labels to determine the new version. The bump-minor and bump-major labels have been set as global GitLab labels. However, global labels only propogate to groups created after setting a global label. When adding a global label, they do not automatically propogate to existing groups⁠.

If you cannot select the specified labels in your merge request, your group was most likely created before the global labels were defined. Please follow this guide to setup group-specific labels⁠.

Tip: You can use custom labels for minor and major bumps by setting the MINOR_BUMP_LABEL and MAJOR_BUMP_LABEL inputs. If not set, the default labels bump-minor and bump-major will be used.

⁠API token and group

To extract the labels from merge requests, we need an API token to access the Gitlab API. Unfortunately, GitLab doesn't yet support non-user specific access tokens⁠.

Ask your GitLab administrator to add a dummy user ${group_name}_npa to GitLab with access only to your project group. Log in with this user, and create a personal access token⁠ with api scope access.

Copy the generated API token and keep it available for the next section.

⁠Group-level variables

The NPA username and token need to be injected into the version-update container as environment variables. For this, we'll use group-level variables.

Go to your group's variables section under Settings -> CI / CD.

Add the following variables:

⁠Merge request instructions

⁠Squash commits when merge request is accepted

The new version will be determined based on the commit message. GitLab will automatically format a merge request commit message if the 'Squash commits when merge request is accepted` checkbox is checked during merge request creation.

⁠Add a label to indicate a minor or major update

As described above, if you want to perform a minor or major update, don't forget to add the appropriate label to your merge request.