Skip to content

Conventional Commits

User Manual

Commitizen is used to validate the format of commit messages. we use Conventional Commit Messages format for our validation jobs.

This repository may have two CI jobs to do with commitizen:

  • MR Title Checks the Merge Request Title

  • Commit Messages Checks all commit messages

These CI Jobs output a test report that can be viewed inside of the merge request and contain the error(s), if any.

To fix an error please refer to the titled sections below.

MR Title

Ensure that the merge request title is in the conventional message format. NOTE: the title is case sensitive.

Commit Messages

All commit messages that form part of your merge request must be in conventional message format.

To fix them go back and edit your commit messages.

fixing commit messages (suggestion)

If only the last commit is the commit with an error just use git commit --amend and edit your commit message to be in the correct format and save. now push your changes.

You will require the following information if the commit message with the error is further down the commit tree:

  • Commit message SHA1 of your first commit message to the branch {original_commit}

  • Commit message SHA1 prior to your first commit {source_commit}

Run these commands once you have the information above.

git format-patch {original_commit}..HEAD -o ../diff-patches

git reset {source_commit} --hard

Now, navigate to the diff-patches folder, open up the offending patch (commit) and edit the subject or message body as appropriate and save. Once all the edits have been done, re-apply the patches to your tree with:

git am ../diff-patches/*.patch

Now push your changes upstream.

:notebook_with_decorative_cover: Note
As you have changed the commit SHA1(s), when you next push your changes upstream, you must force push. git push --force
:octagonal_sign: WARNING
Ensure that all of your commits were exported prior to reseting the branch and when re-applying, that all of your commits were applied correctly

GitLab CI Template - .conventional_commit

This GitLab CI template, named .conventional_commit, is designed to validate conventional commits within a GitLab CI/CD pipeline. It follows predefined rules to ensure that commit message conventions are met.

your .gitlab-ci.yml changes

To use this job add the following to your .gitlab-ci.yml file

variables:
    GIT_SUBMODULE_STRATEGY: recursive
    MY_PROJECT_ID: "{yourproject id number}"

stages:
    - validation

include:
    - remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/development/conventional_commits/.gitlab-ci.yml

Job Description

The .conventional_commit job performs various tasks related to validating conventional commits. It runs in the validation stage of the pipeline and uses the python:3.6-slim Docker image.

Variables

  • DEFAULT_ROOT_DIR: The default root directory is set as ./gitlab-ci.

  • MR_ACCESS_TOKEN: The access token for the merge request. If not defined, it falls back to CI_JOB_TOKEN.

  • JOB_ROOT_DIR: The root directory for the job. If not defined, it falls back to DEFAULT_ROOT_DIR.

  • MY_PROJECT_ID: The custom project ID. If not defined, it falls back to CI_PROJECT_ID.

Stages

  • validation: The job is assigned to the validation stage.

Script

The script section contains the actions performed during the job execution. These actions include creating directories, setting up variables, preparing the Python environment, and executing commands related to validating conventional commits.

The complete script can be found in the GitLab CI template file.

Artifacts

The job generates artifacts that are stored for a period of 3 days. The artifacts include the following paths:

  • $CI_PROJECT_DIR/artifacts/*

  • $CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/*.junit.xml

Rules

The job follows certain rules to determine when it should be executed:

  • If the variable $JOB_STOP_CONVENTIONAL_COMMITS is true, the job will not run.

  • If the branch is pushed and a commit is made, and there is no tag associated with the commit, and the pipeline source is "push", the job will run if .cz.yaml file exists.

  • In all other cases, the job will not run.

This GitLab CI template provides a convenient way to validate conventional commits and enforce commit message conventions within your CI/CD pipelines.

Gitlab job Definition

When you include this definition the following makes up the job definition

.gitlab-ci.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
.conventional_commit:
  variables:
    DEFAULT_ROOT_DIR: './gitlab-ci'
  image: python:3.6-slim
  stage: validation
  before_script:
    - mkdir -p "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME"
    - mkdir -p "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests"
    - if [ "0$MR_ACCESS_TOKEN" == "0" ]; then MR_ACCESS_TOKEN=$CI_JOB_TOKEN; fi
    - echo "[DEBUG] MR_ACCESS_TOKEN[$MR_ACCESS_TOKEN]"
    - if [ "0$JOB_ROOT_DIR" == "0" ]; then ROOT_DIR=$DEFAULT_ROOT_DIR; else ROOT_DIR=$JOB_ROOT_DIR ; fi
    - echo "[DEBUG] ROOT_DIR[$ROOT_DIR]"
    - if [ "0$MY_PROJECT_ID" == "0" ]; then PROJECT_ID=$CI_PROJECT_ID; else PROJECT_ID=$MY_PROJECT_ID ; fi
    - echo "[DEBUG] PROJECT_ID[$PROJECT_ID]"
    - export PYTHON_VERSION=`python -c 'import sys; version=sys.version_info[:3]; print("{0}.{1}.{2}".format(*version))'`
    - apt update
    - apt install --no-install-recommends -y git
    - python3 -m venv env
    - . env/bin/activate
    - pip install --upgrade pip
    - pip install -r $ROOT_DIR/conventional_commits/requirements.txt
    - echo "[DEBUG] CI_PROJECT_ID[$CI_PROJECT_ID]"
    - echo "[DEBUG] CI_COMMIT_BRANCH[$CI_COMMIT_BRANCH]"
    - git fetch --all
    - git checkout --track origin/$CI_COMMIT_BRANCH
    - git show-branch -a
    - target_branch=$(git show-branch -a | awk 'BEGIN { FS="\n\s+*" } { print $1 }' | awk '{print $2}' | grep '\[' | sed 's/.*\[origin\/\(.*\)\].*/\1/' | grep -v '\[' | grep -v $(git rev-parse --abbrev-ref HEAD) | grep -vi 'HEAD' | awk 'BEGIN{ RS = "" ; FS = "\n" }{print $1}')
    - echo "[DEBUG] Target Branch[$target_branch]"
    - if [ -d "gitlab-ci" ]; then ls -la gitlab-ci; fi
    - first_sha1=$(git log origin/$target_branch..$CI_COMMIT_BRANCH --format=format:%H | tail -1)
    - echo "[DEBUG] First Commit SHA[$first_sha1]"
    - echo "[DEBUG] artifacts directory [$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME]"
  after_script:
    - ls -lR "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE"
    - cd ..
    - rm -Rf check
  artifacts:
    expire_in: 3 days
    when: always
    paths:
      - "$CI_PROJECT_DIR/artifacts/*"
    reports:
      junit:
        - "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/*.junit.xml"
  rules:
    - if: '$JOB_STOP_CONVENTIONAL_COMMITS'
      when: never

    - if:  # condition_any_branch_push
        $CI_COMMIT_BRANCH != null && 
        $CI_COMMIT_TAG == null &&
        $CI_PIPELINE_SOURCE == "push" &&
        $CI_COMMIT_BRANCH != 'master'
      exists:
      - .cz.yaml
      when: always

    - when: never


MR Title:
  extends:
    - .conventional_commit
  script:
    - MR_TITLE=$($ROOT_DIR/conventional_commits/scripts/commit.py --token "$MR_ACCESS_TOKEN" --project $PROJECT_ID --title --branch $CI_COMMIT_BRANCH)
    - echo "[DEBUG] MR_TITLE[$MR_TITLE]"
    - cz_exit=0 && cz check --message "$MR_TITLE" > "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/cz_output.log" 2>&1 || cz_exit=$?
    - . $ROOT_DIR/conventional_commits/scripts/cz_junit.sh > "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/$CI_JOB_NAME-cz.junit.xml"


Commit Messages:
  extends:
    - .conventional_commit
  script:
    - if [ "$(git log $first_sha1..HEAD --format=format:%H | wc -l)" -eq 0 ]; then echo "[DEBUG] Single Commit"; cz_exit=0 && cz check -m "$(git log HEAD --format=format:%B -1)" > "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/cz_output.log" 2>&1 || cz_exit=$?; fi 
    - if [ "$(git log $first_sha1..HEAD --format=format:%H | wc -l)" -gt 0 ]; then echo "[DEBUG] Commit range";  cz_exit=0 && cz check --rev-range $first_sha1..HEAD > "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/cz_output.log" 2>&1 || cz_exit=$?; fi
    - . $ROOT_DIR/conventional_commits/scripts/cz_junit.sh > "$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/$CI_JOB_NAME-cz.junit.xml"

About:

This page forms part of our Project Gitlab-CI.

Page Metadata
Version: ToDo: place files short git commit here
Date Created: 2021-08-03
Date Edited: 2023-06-10

Contribution:

Would You like to contribute to our Gitlab-CI project? You can assist in the following ways:

 

ToDo: Add the page list of contributors