Pre-requisites

  • GitLab Account
  • GitHub Account

Objectives

Create a CI/CD pipeline to automate versioning and CHANGELOG file generation

Example

Understanding Semantic Versioning (SemVer)

Semantic Versioning (SemVer) is a versioning scheme for software that uses a three-part number format: MAJOR.MINOR.PATCH (e.g., 1.2.3). This approach helps developers and users understand the impact of new releases at a glance.

The format for SemVer is:

  • MAJOR: Increased when you make incompatible API changes.
  • MINOR: Increased when you add functionality in a backward-compatible manner.
  • PATCH: Increased when you make backward-compatible bug fixes.

For example, 1.0.0 might be the initial release, and future releases could look like:

  • 1.1.0 for a minor, backward-compatible feature addition.
  • 1.1.1 for a bug fix that doesn’t affect the API.
  • 2.0.0 for breaking changes.

Implementing automatic versioning and changelog generation

GitLab provides powerful CI/CD pipelines that can be leveraged to automate semantic versioning. You can use Git tags and GitLab CI/CD pipelines to automatically apply and increment version numbers as part of your release process.

GitLab - Automatic versioning

  1. Create .gitlab-ci.yml file in a git repository
stages:
  - release

release:
  image: node:latest
  stage: release
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends git-core ca-certificates
    - npm install -g semantic-release @semantic-release/gitlab @semantic-release/changelog conventional-changelog-conventionalcommits @semantic-release/commit-analyzer @semantic-release/git
  script:
    - semantic-release
  only:
    - master # change branch name if different

semantic-release is a tool used to automatically determine and apply the next version based on converional commits

  1. Create a CI/CD variable with a Project Token

    1. Project Setting -> Access Token -> Add new token. (Scope api) Check scope here
    2. Project Setting -> CICD -> create a var named GITLAB_TOKEN and paste the token generetad in previous step

  2. Create a file named .releaserc and paste the following code:

{
  "branches": ["master"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/git",
    [
      "@semantic-release/gitlab",
      {
        "gitlabUrl": "https://gitlab.com"
      }
    ]
  ]
}

NOTE. In .releaserc the order is important in order for plugins to work

✅ After running the pipeline a new git tag and a CHANGELOG.md file have been created !

GitHub - Automatic versioning

  1. Create .github/worflows/release.yml file in a git repository
name: Release
"on":
  push:
    branches:
      - main
permissions:
  contents: read # for checkout
jobs:
  release:
    permissions:
      contents: write # to be able to publish a GitHub release
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for npm provenance
    name: release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
      - uses: actions/setup-node@0a44ba7841725637a19e28fa30b79a866c81b0a6 # v4.0.4
        with:
          cache: npm
          node-version: lts/*
      - run: npm install -g semantic-release @semantic-release/github @semantic-release/changelog conventional-changelog-conventionalcommits @semantic-release/commit-analyzer @semantic-release/git
      - run: semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          #NPM_TOKEN: ${{ secrets.SEMANTIC_RELEASE_BOT_NPM_TOKEN }}

At the start of each workflow job, GitHub automatically creates a unique GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in the workflow job.

If you still want to create a GITHUB_TOKEN

  1. Create a Personal Access Token (classic)

    1. Settings -> Developer Settings -> Personal access tokens (classic) named GITUB_TOKEN

    When creating the token, the minimum required scopes are: repo for a private repository public_repo for a public repository

    1. Add secret to Project Setting

  2. Create a file named .releaserc and paste the following code:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md"]
      }
    ],
    [
      "@semantic-release/github",
      {
        "githubUrl": "https://github.com"
      }
    ]
  ]
}

NOTE. In .releaserc the order is important in order for plugins to work

✅ After running the pipeline a new git tag and a CHANGELOG.md file have been created !