Keeping track of what commit relates to which release of your Git projects requires making sure that you tag the commits with the related version. This can be manually done when you release a new version (if you remember), or automatically with the help of continuous integration (CI) pipelines.

I had previously hacked together a job to do this using git commands and a masked URL containing an API key (like in the example below), but recently found the release-cli project and docker container for doing the same in a much cleaner fashion.

tag:
  stage: tag
  script:
    - export VERSION=$(node -e "console.log(require('./package.json').version)")
    - git status
    - git remote -v
    - git remote set-url origin ${SECRET_URL}
    - git tag v$VERSION
    - git push origin v$VERSION
  only:
    - master

release-cli

The release-cli docker container is able to both create a git tag and a Gitlab release, for which you can give information on the release, such as what has changed.

Creating a job to create the release using release-cli is fairly straight forward.

tag:
  stage: tag
  image: registry.gitlab.com/gitlab-org/release-cli
  script:
    - |
      release-cli --server-url $CI_SERVER_URL --job-token $CI_JOB_TOKEN \
      --project-id $CI_PROJECT_ID create --name "Release v${VERSION}" \
      --description "$DESCRIPTION" --tag-name "v${VERSION}" \
      --ref $CI_COMMIT_SHA
  variables:
    # Ensures submodules are not pulled
    GIT_SUBMODULE_STRATEGY: none
  only:
    - master

And if you are using Gitlab >=13.2 it is even easier with the release keyword

tag:
  release:
    tag_name: v${VERSION}
    description: ${DESCRIPTION}
  only:
    - master

The only more difficult thing you need to do is specify the version and the description for the release.

Details Sniffer

As I keep a CHANGELOG of all the changes I make in most of my projects, I decided to pull the release description from that and get the version number from either the package.json file (for NPM projects) or from the setup.py file (for Python projects).

To do this, I used the powerful sed utility to:

1. extract the version from the package.json/setup.py file
2. extract the lines from the CHANGELOG.md between the current version header and the previous version header.

tag:
  stage: tag
  image: registry.gitlab.com/gitlab-org/release-cli
  script:
    - |
      # Get the version from either the package.json or the setup.py file
      if [ -e package.json ]; then
        VERSION=$(cat package.json | sed -n "s/^.*\"version\": \"\\(.*\\)\".*$/\1/p")
      elif [ -e setup.py ]; then
        VERSION=$(cat setup.py | sed -n "s/^.*version='\\(.*\\)'.*$/\1/p")
      fi

      if [ "$VERSION" != "" ]; then
        # Get the version details from the CHANGELOG if we have one
        if [ -e CHANGELOG.md ]; then
          DESCRIPTION=$(cat CHANGELOG.md | sed -e "1,/$(echo $VERSION | sed 's/\\./\\\\./')/d" | sed -e '/^## /,$d')
        else
          DESCRIPTION="Release v$VERSION"
        fi
        # Get the current tag of the commit (to ensure it hasn't already been tagged)
        CURRENT_TAG=$(git describe --tags 2>/dev/null || true)
        if [ "$CURRENT_TAG" != "v$VERSION" ]; then
          release-cli --server-url $CI_SERVER_URL --job-token $CI_JOB_TOKEN \
          --project-id $CI_PROJECT_ID create --name "Release v${VERSION}" \
          --description "$DESCRIPTION" --tag-name "v${VERSION}" \
          --ref $CI_COMMIT_SHA
        fi
      fi
  variables:
    # Ensures submodules are not pulled
    GIT_SUBMODULE_STRATEGY: none
  only:
    - master

With the job updated, it was time to test. Luckily, I needed to publish a new version of keeps-on-ticking.

I prepared the merge request and when it was ready hit merge. It worked like a charm and produced Release v1.1.0.