Releases

Release Versioning

Release versioning is automated by combining our Versioning strategy with the Semantic Release package integrated into our GitLab CI.

For example, consider the following commit message:

fix(api): /user endpoint now accepts mythical figures, including Norse Gods

Closes #1

When the developer attempts to commit this to the allow-thor branch the release process proceeds as follows:

1. The dev attempts to commit the change to the non-master branch (allow-thor).
2. The commit message is validated.
3. The commit is pushed to the allow-thor branch on GitLab.
4. GitLab CI performs the testing environment deployment process, as defined in .gitlab-ci.yml.
5. If all testing environment pipeline stages succeed, the dev can now create a merge request to merge allow-thor into the master branch.
6. Once the merge request is accepted GitLab CI executes the production environment pipeline.
7. At the end of the production deployment pipeline is the release stage, which uses Semantic Release to analyze the full collection of commits within the merge request.
8. The proper new version number (tag) is automatically generated, based on the semantic versioning rules defined by our active Commit Message Syntax.
9. A changelog is auto-generated and associated with the tagged release.

Our full Semantic Release configuration can be found in the .releaserc.json file.

How to Add Releasing to an Existing Project

1. Add any missing node modules to package.json:

• Bash
• PowerShell

yarn add -D @commitlint/cli @commitlint/config-conventional @semantic-release/git @semantic-release/gitlab \
    @semantic-release/npm commitizen cz-conventional-changelog husky

yarn add -D @commitlint/cli @commitlint/config-conventional @semantic-release/git @semantic-release/gitlab `
    @semantic-release/npm commitizen cz-conventional-changelog husky

2. Add a config: commitizen section to package.json:

{
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}

3. Add a commit script to package.json:

{
  "scripts": {
    "commit": "git-cz"
  }
}

4. Copy .commitlintrc.js, .huskyrc.js, and .releaserc.json files to project root directory.
5. Update repositoryUrl and @semantic-release/gitlab: gitlabUrl in .releaserc.json to match the private GitLab repo endpoint and URL, respectively:

{
  "repositoryUrl": "git@gitlab.solarixdigital.com:path/to/project.git",
  "plugins": [
    [
      "@semantic-release/gitlab",
      {
        "gitlabUrl": "https://gitlab.solarixdigital.com/path/to/project"
      }
    ]
  ]
}

6. Add a new release stage to .gitlab-ci.yml and add a matching production:release job:

stages:
  # ...
  - release

# ...
production:release:
  stage: release
  only:
    - master
  environment:
    name: production
  image: node:12-buster-slim
  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/git conventional-changelog-conventionalcommits
  script:
    - semantic-release

7. On GitLab create a new Personal Access Token with api scope.
8. Under Project > Settings > CI / CD > Variables create a new GITLAB_TOKEN variable with the generated token as the value.

Now, the next production pipeline CI should evaluate the commit history and perform a semantic release, if necessary.