@gitlab/truncated-tags

A semantic-release plugin that creates and updates truncated Git tags using the GitLab API instead of Git commands. This plugin is designed to work with GitLab's protected tags feature and provides the ability to create truncated version tags (e.g., v1.2).

Why Use This Plugin?

Renovate is an excellent tool for keeping dependencies updated, but it can generate significant maintenance overhead through frequent update merge requests. With truncated version tags (e.g., v1.2 instead of v1.2.3), Renovate only creates merge requests for minor or major version changes, not for every patch release. This dramatically reduces the "noise" from constant update notifications while still keeping your dependencies current.

However, GitLab's protected tags feature prevents truncated tags from being deleted or modified through standard git operations. Removing the tag protection means that pipelines running on these tags may not have access to secrets requires for the deployment process.

This plugin solves this dilemma by managing truncated tags through the GitLab API, allowing tags to remain protected.

Installation

npm install --save-dev @gitlab-com/truncated-tags

Configuration

1. Add this plugin to your package.json file:

   {
     "devDependencies": {
       "@gitlab/truncated-tags": "^1.0.0"
     }
   }

2. Add this plugin to your semantic-release configuration file, e.g. .releaserc.json:

   {
     "branches": ["main"],
     "plugins": [
       "@semantic-release/commit-analyzer",
       "@semantic-release/release-notes-generator",
       "@gitlab/truncated-tags",
       "@semantic-release/gitlab"
     ]
   }

   Make sure to place this plugin before @semantic-release/gitlab in your plugins list.

Required Environment Variables

• GITLAB_TOKEN: A GitLab personal access token or CI token with API access to manage tags
• CI_PROJECT_PATH: GitLab project path (automatically set in GitLab CI/CD pipelines)
• CI_API_V4_URL: GitLab API URL (automatically set in GitLab CI/CD pipelines)

How It Works

1. Validate Version: Checks if the new version is suitable for truncation (e.g., has more than two parts).
2. Handle Existing Tags: If a tag already exists, the plugin will delete and recreate it via the GitLab API.
3. Create Truncated Version Tag: Creates a tag with only the major and minor version components (e.g., v1.2).

Custom Options

The plugin currently doesn't support custom configuration options.

License

MIT License, see LICENSE file.