semantic-release-gitlab

Automatically publish packages to the npm registry for source code hosted on GitLab.

semantic-release-gitlab is designed to automate the process of releasing GitLab-hosted code to an npm registry.

Releasing GitLab-hosted code to an npm registry may include:

• Getting a list of all commits to a project that have not been published.
• Determining the appropriate semantic version to release.
• Generating a git tag for the repository on GitLab with that version.
• Publishing a list of changes included in that version.
• Publishing an npm package containing those changes to an npm registry.
• Informing people subscribed to GitLab issues or merge requests about the release.

By automating these steps semantic-release-gitlab alleviates some of the overhead in managing a project, allowing you to quickly and consistently publish enhancements that provide value to your consumers.

This idea, however, is not new. semantic-release-gitlab was heavily inspired by the work of semantic-release. If you have a GitHub project you're highly encouraged to check out semantic-release.

Features

• [✓] Get a list of unpublished commits using git-raw-commits.
• [✓] Detect commit message convention used by a project with conventional-commits-detector.
• [✓] Determine appropriate version to publish with conventional-recommended-bump.
• [✓] Publish package to the npm registry.
• [✓] Publish a GitLab release using conventional-gitlab-releaser through the semantic-release-gitlab-releaser plugin.
• [✓] Create an annotated git tag that can be fetched from GitLab.
• [✓] Post a comment to GitLab issues closed by changes included in a package release through semantic-release-gitlab-notifier plugin.

Installation

To install the semantic-release-gitlab tool for use in your project's release process please run the following command:

npm install --save-dev semantic-release-gitlab

Usage

Once installed semantic-release-gitlab may be invoked by executing the CLI tool exported by the package. Installed into your project's node_modules bin directory is the semantic-release-gitlab executable. It can be invoked directly by calling $(npm bin)/semantic-release-gitlab. To learn how semantic-release-gitlab can be used as part of your project's release process please see the Continuous Integration and Delivery (CID) Setup section below.

First step of semantic-release-gitlab is to get a list of commits made to your project after the latest semantic version tag. If no commits are found, which typically occurs if the latest commit in your project is pointed to by a semantic version tag, then semantic-release-gitlab will exit cleanly, and indicate that no changes can be released. This ensures you can run the release process multiple times only releasing new versions if there are unreleased commits. If commits are available, semantic-release-gitlab will proceed onto the next step.

As noted under Features we determine the commit convention used by your project with conventional-commits-detector. Once we have determined your commit message convention we pass that information on to conventional-recommended-bump to determine the appropriate version to publish.

By default conventional-recommended-bump will recommend at least a patch release. Depending on the commit convention you follow, commits may be released as a major or minor release instead. For more information on how versions are determined, please see the Version Selection section below.

For more on the meanings of patch, minor, and major, please see Semantic Versioning.

Required Environment Settings

For semantic-release-gitlab to publish packages to the npm registry, and a changelog to GitLab, several environment variables must be setup within your continuous integration job.

| Required Token | Environment Variable Name | | ------------------ | ----------------------------- | | npm token | NPM_TOKEN | | GitLab Private Token | GITLAB_AUTH_TOKEN |

The account associated with the GitLab private token must have Developer permissions on the project to be released to meet the requirements of semantic-release-gitlab-releaser. GitLab permissions are documented on the GitLab Permissions site.

Setting HTTP Protocol for GitLab Integration

By default all API calls to GitLab are made over HTTPS. If, for some reason, that's impossible, those API calls can be made over HTTP instead. To use HTTP set the environment variable GITLAB_INSECURE_API to true. Other values, including not setting the environment variable, will cause semantic-release-gitlab to use HTTPS.

We strongly advise against communicating with GitLab over HTTP, but this option is supported for those cases where configuring SSL for GitLab is not feasible.

Continuous Integration and Delivery (CID) Setup

Since semantic-release-gitlab relies solely on a few environment variables, and a package published on the public npm registry, semantic-release-gitlab is compatible with all continuous integration platforms that work with GitLab.

However, given the enormous number of CI providers available I will only cover the CI system built into GitLab.

Configuring GitLab CI builds is facilitated through a .gitlab-ci.yml configuration file. To publish changes using semantic-release-gitlab you will need to create a dedicated build stage that happens only after all other build and test tasks have completed successfully.

In GitLab CI that is possible by creating a dedicated deploy stage and adding it as the last item under stages. Next, create a job called publish that belongs to the deploy stage. Within publish we call semantic-release-gitlab.

You can see a snippet of a .gitlab-ci.yml file with this setup below:

stages:
  - build
  - test
  - deploy

publish:
  before_script:
    - npm install semantic-release-gitlab
  only:
    - master@<GROUP>/<PROJECT>
  script:
    - $(npm bin)/semantic-release-gitlab
  stage: deploy

Full documentation for GitLab CI is available on the GitLab CI website.

You may also take a look at our .gitlab-ci.yml file as an example.

Publishing Elsewhere Besides Public npm Registry

It's possible to publish your package to any npm registry, not just the official public registry. When publishing a package semantic-release-gitlab uses the built-in publish command of npm. Any features supported by npm publish are available. For example, you may specify, on a per-project basis, which registry to publish your package to by setting the publishConfig property in your project's package.json file.

Alternative registries may include on-premise solutions such as Artifactory and npm enterprise.

Version Selection

As noted earlier semantic-release-gitlab uses conventional-recommended-bump to determine the version to use when publishing a package. If conventional-recommended-bump indicates that no valid version could be determined, typically because it believes no new version should be released, then semantic-release-gitlab will not publish the package.

Rules used by conventional-recommended-bump are housed in it's repository. If you have any questions or concerns regarding those rules, or the version provided by conventional-recommended-bump, please reach out to their project on GitHub.

Debugging

To assist users of semantic-release-gitlab with debugging the behavior of this module we use the debug utility package to print information about the release process to the console. To enable debug message printing, the environment variable DEBUG, which is the variable used by the debug package, must be set to a value configured by the package containing the debug messages to be printed.

To print debug messages on a unix system set the environment variable DEBUG with the name of this package prior to executing semantic-release-gitlab:

DEBUG=semantic-release-gitlab semantic-release-gitlab

On the Windows command line you may do:

set DEBUG=semantic-release-gitlab
semantic-release-gitlab

All semantic-release-gitlab plugins use debug to print information to the console. You can instruct all plugins, and semantic-release-gitlab, to print their debugging information by using semantic-release-gitlab* as the value of the DEBUG environment variable.

DEBUG=semantic-release-gitlab* semantic-release-gitlab

semantic-release-gitlab uses numerous other npm packages and many of those use the debug utility package as well. For example to print the debug messages from npm-utils you may assign semantic-relesae-gitlab and npm-utils to the DEBUG environment variable like so:

DEBUG=semantic-release-gitlab,npm-utils semantic-release-gitlab

You may also print debug messages for the underlying HTTP request library, request, by setting the NODE_DEBUG environment variable to request, as shown in their documentation.

Contributing

Please read our contributing guide on how you can help improve this project.