# @hacksawstudios/gitlab-ci-releaser > Yet another conventional GitLab releaser Latest version **3.0.6** (published 2025-10-01) · MIT license · 0 weekly downloads ## Install ```sh npm install @hacksawstudios/gitlab-ci-releaser pnpm add @hacksawstudios/gitlab-ci-releaser yarn add @hacksawstudios/gitlab-ci-releaser bun add @hacksawstudios/gitlab-ci-releaser ``` Provides the command `gitlab-ci-releaser`. ## Health **Score 45/100 (D)** — status: stable. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. ## Facts | | | |---|---| | Version | 3.0.6 | | Published | 2025-10-01 | | First published | 2018-03-14 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 14 | | Unpacked size | 45.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Iheb Khemissi | | Maintainers | karl_r, hacksaw_studios | | Keywords | conventional, gitlab, semantic, release, npm, changelog | ## Links - npm: https://www.npmjs.com/package/@hacksawstudios/gitlab-ci-releaser - Repository: https://gitlab.hacksawstudios.com:gameclient/client-tools/gitlab-ci-releaser - Homepage: https://gitlab.com/ikhemissi/gitlab-ci-releaser#README - Issues: https://gitlab.com/ikhemissi/gitlab-ci-releaser/issues - npm.io page: https://npm.io/package/@hacksawstudios/gitlab-ci-releaser ## Dependencies (14) - [semver](https://npm.io/package/semver.md) ^5.7.1 - [commander](https://npm.io/package/commander.md) ^2.20.3 - [handlebars](https://npm.io/package/handlebars.md) ^4.7.7 - [semver-sort](https://npm.io/package/semver-sort.md) 0.0.4 - [registry-url](https://npm.io/package/registry-url.md) ^4.0.0 - [es6-promisify](https://npm.io/package/es6-promisify.md) ^6.1.1 - [@gitbeaker/node](https://npm.io/package/@gitbeaker/node.md) ^32.1.1 - [git-raw-commits](https://npm.io/package/git-raw-commits.md) ^2.0.10 - [git-semver-tags](https://npm.io/package/git-semver-tags.md) ^4.1.1 - [stream-to-array](https://npm.io/package/stream-to-array.md) ^2.3.0 - [tagged-versions](https://npm.io/package/tagged-versions.md) ^1.3.0 - [child-process-promise](https://npm.io/package/child-process-promise.md) ^2.2.1 - [cz-conventional-changelog](https://npm.io/package/cz-conventional-changelog.md) ^3.3.0 - [conventional-commits-parser](https://npm.io/package/conventional-commits-parser.md) ^3.2.1 ## Alternatives - [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads - [log](https://npm.io/package/log.md) — 1.3M weekly downloads - [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads - [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads - [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads ## Recent versions - 3.0.6 (latest) — 2025-10-01 - 3.0.5 — 2021-08-11 - 3.0.4 — 2021-08-11 - 3.0.3 — 2021-08-11 - 3.0.2 — 2021-08-11 - 3.0.1 — 2021-08-11 - 3.0.0 — 2021-08-10 - 2.0.6 — 2021-08-10 - 2.0.5 — 2021-08-10 - 2.0.4 — 2021-08-10 - 2.0.3 — 2021-08-10 - 2.0.2 — 2021-07-12 - 2.0.1 — 2018-10-09 - 2.0.0 — 2018-06-13 - 1.7.6 — 2018-06-13 - … 10 more at https://npm.io/package/@hacksawstudios/gitlab-ci-releaser/versions ## README Fork of https://gitlab.com/ikhemissi/gitlab-ci-releaser with the following changes: 1. preid You can add preid to your command to be able to have for example "1.0.0-rc.0" as version. preid will be incremented when using command with preid set. For example stay you start a new project and you have package version "1.0.0". After running ```gitlab-ci-releaser --preid rc``` version will be comiited as "1.0.0-rc.0". Now if you run ```gitlab-ci-releaser --preid rc``` again it will become "1.0.0-rc.1", and once more rc.2, etc. Whenever you run ```gitlab-ci-releaser``` the preid will be discarded, and version according to above example would be commited as "1.0.0". This is useful if you have a flow where you have feature branches you merge down to a development branch, and then merge to a stable/master branch to make a final delivery release. Then in your gitlab-ci.yml for the scripts running from develop you run with preid to get release candidate versions tagged and published to npm, and from master branch you run without preid to get final release versions. 2. Updated gitlab environment variables. Following vars has been renamed: CI_BUILD_REPO -> CI_REPOSITORY_URL CI_BUILD_ID -> CI_JOB_ID CI_BUILD_REF_NAME -> CI_COMMIT_REF_NAME Original documentation: # gitlab-ci-releaser > Yet another conventional GitLab releaser : find unreleased changes, bump version, commit/push changes and create a new GitLab release with notes ## Installation The setup requires Node 6+. 1. Add a new release stage in your [.gitlab-ci.yml](https://docs.gitlab.com/ce/ci/yaml/README.html). 2. Install `gitlab-ci-releaser` using `npm install gitlab-ci-releaser` 3. Add the environment variables `GITLAB_CI_RELEASER_NAME`, `GITLAB_CI_RELEASER_EMAIL` and `GITLAB_CI_RELEASER_TOKEN` with settings of a user having `Developer` permissions and the permission to push to the release branch (e.g. `master`). 4. Optionally, add an environment variable `NPM_TOKEN` if you want to publish your packages to a npm registry. I recommend creating and using a new user with `Developer` + push permissions, adding the user to the project members and generating all the environment variables using this user account (the SSH access permissions are not needed for this account). ## Usage You can use the `gitlab-ci-releaser` command to create releases: ```sh $(npm bin)/gitlab-ci-releaser ``` To publish to npm, add the `npm` option: ```sh $(npm bin)/gitlab-ci-releaser --npm ``` You can optionally pass the npm registry and authentication token via command line arguments: ```sh $(npm bin)/gitlab-ci-releaser --token "" --npmToken "" --npmRegistry "http://localhost:4873/" ``` This being said, I strongly recommend using environment variables for this sensitive information instead of passing them as program arguments. Here is an example of GitLab CI stage for releasing with npm publishing. ``` image: node:6 stages: - build - release build: stage: build script: - npm install release: stage: release before_script: - npm install gitlab-ci-releaser only: - master script: - $(npm bin)/gitlab-ci-releaser --npm when: manual ``` ## Environment variables `gitlab-ci-releaser` relies on many environment variables: | Name | Type | Set by | Description | Example | |--------------------------|-----------|-----------|---------------------------------------------------------|--------------------------------------------------------------------------------------------| | `GITLAB_CI_RELEASER_NAME` | Mandatory | Admin | GitLab account username, used to create release commits | ikhemissi | | `GITLAB_CI_RELEASER_EMAIL` | Mandatory | Admin | GitLab account email, used to create release commits | mail.address@example.com | | `GITLAB_CI_RELEASER_TOKEN` | Mandatory | Admin | GitLab account access token, used to push commits | aBcde1234AbcD5678ef | | `NPM_TOKEN` | Optional | Admin | NPM authToken. Only needed when publishing to NPM. | 9febf68b-f1b7-5bd9-701a-576eba203a1f3 | | `NPM_REGISTRY` | Optional | Admin | NPM registry. By default, it will be fetched from npm configuration | http://private.sinopia.registry:4873/ | | `CI_PROJECT_URL` | Mandatory | GitLab CI | Project url | https://gitlab.com/ikhemissi/test-release-project | | `CI_PROJECT_PATH` | Mandatory | GitLab CI | Project ID (user name + project name) | ikhemissi/test-release-project | | `CI_REPOSITORY_URL` | Mandatory | GitLab CI | Project repository | https://gitlab-ci-token:xxxx@gitlab.com/ikhemissi/test-release-project.git | | `CI_COMMIT_REF_NAME` | Mandatory | GitLab CI | Project branch used in the build | master | | `GITLAB_USER_EMAIL` | Optional | GitLab CI | Email of the user who triggered the build | mail.address@example.com | | `CI_JOB_ID` | Optional | GitLab CI | Internal GitLab build number | 50 | ## Release versions By default, `gitlab-ci-releaser` uses [semantic commit](https://seesparkbox.com/foundry/semantic_commit_messages) types and footers to determine the next release [version](http://semver.org/): - if this is the first release, then the version `1.0.0` will be used to create the release - if the new changes include a commit with a breaking change (the commit message contains `BREAKING CHANGE`) then a major release will be created - if there is at least one feature commit (commit type = `feat`), then a minor release will be created - otherwise, a patch release will be created This being said, you can force a specific release type or version as long as they conform to the [semver spec](http://semver.org/) using the following options: - `releaseType`: This option allows you to force a specific release version increment (e.g. major, minor, patch). For example, by running `gitlab-ci-releaser --releaseType major` we get a version `2.0.0` if the previous one was `1.5.0`, and we get `4.0.0` if the previous one was `3.0.0`. - `releaseVersion`: With this option, you can force using a specific release version (e.g. 1.9.1). For example, by running `gitlab-ci-releaser --releaseVersion 1.9.1` we create a release having the version `1.9.1` **even if the previous one was `2.0.0`, which may lead to potential issues**. Please note that the semantic commits are also used to generate the release notes, so I don't recommend using the `releaseType` and `releaseVersion` unless your project do not use semantic commits. If you plan to switch to semantic commits, I strongly suggest using a tool like [commitizen](https://www.npmjs.com/package/commitizen) to create your commits and have better commit messages. ## Similar projects - [semantic-release-gitlab](https://www.npmjs.com/package/semantic-release-gitlab): this project inspired me to write gitlab-ci-releaser. Many thanks to Hutson. - [gitlab-release](https://www.npmjs.com/package/gitlab-release) ## Contributing Please follow the [Airbnb guidelines](https://github.com/airbnb/javascript) and commit your changes with [commitzen](https://www.npmjs.com/package/commitizen) using `git cz`. --- _Source: https://npm.io/package/@hacksawstudios/gitlab-ci-releaser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._