semantic-release-merge-request-analyzer

A semantic-release plugin that determines the next version based on GitLab merge request labels and generates release notes from merge request information.

Features

• Determines version bump (major, minor, patch, etc.) based on GitLab merge request labels
• Supports all semantic-release version types: major, premajor, minor, preminor, patch, prepatch, prerelease
• Fully customizable label mapping for determining release types
• Generates structured release notes from merge request information
• Integrates with GitLab CI/CD environment variables

Installation

npm install --save-dev "@gitlab/semantic-release-merge-request-analyzer"

Default Label Configuration

By default, this plugin recognizes the following labels:

• breaking change - Triggers a major release
• type::feature - Triggers a minor release
• type::bug - Triggers a patch release
• type::maintenance - Does not trigger a release (maintenance work)

However, you can fully customize which labels map to which release types.

Configuration

Environment Variables

The plugin requires the following environment variables:

• CI_SERVER_URL: The base URL of the GitLab instance, including protocol and port (automatically set in GitLab CI, default: https://gitlab.com)
• CI_PROJECT_ID: The GitLab project ID (automatically set in GitLab CI)
• GITLAB_TOKEN: A GitLab access token with API access

semantic-release Configuration

Add the plugin to your .releaserc.json or release.config.js:

{
  "plugins": [
    "@gitlab/semantic-release-merge-request-analyzer",
    "@semantic-release/gitlab"
  ]
}

Custom Label Configuration

You can customize which labels trigger which release types:

{
  "plugins": [
    [
      "@gitlab/semantic-release-merge-request-analyzer",
      {
        "labels": {
          "major": ["breaking change", "breaking-change"],
          "premajor": ["pre-major"],
          "minor": ["type::feature", "feature", "feat"],
          "preminor": ["pre-minor"],
          "patch": ["type::bug", "bug", "fix"],
          "prepatch": ["pre-patch"],
          "prerelease": ["pre-release"]
        }
      }
    ],
    "@semantic-release/gitlab"
  ]
}

The plugin supports all standard semantic-release version types:

• major - Backward-incompatible changes
• premajor - Pre-release for the next major version
• minor - New features (backward-compatible)
• preminor - Pre-release for the next minor version
• patch - Bug fixes
• prepatch - Pre-release for the next patch version
• prerelease - General pre-release

If a merge request has multiple labels that would trigger different release types, the plugin chooses the highest release type based on the precedence (major > premajor > minor > preminor > patch > prepatch > prerelease).

If a merge request doesn't have any of the configured labels, it won't trigger a release.

Function-Specific Configuration

Alternatively, if you want to use only specific functions from this plugin:

{
  "plugins": [
    [
      "@gitlab/semantic-release-merge-request-analyzer",
      {
        "analyzeCommits": true,
        "generateNotes": true,
        "labels": {
          "major": ["breaking"],
          "minor": ["feature"],
          "patch": ["fix"]
        }
      }
    ],
    "@semantic-release/gitlab"
  ]
}

How It Works

1. Verify Conditions: Checks that required environment variables are present.
2. Analyze Commits: For each commit, the plugin:
   • Finds the associated GitLab merge request
   • Examines the merge request labels to determine if a release is needed
   • Determines release type (major, minor, patch, etc.) based on configured label mapping
   • Selects the highest precedence release type among all analyzed merge requests
3. Generate Notes: Creates structured release notes based on merge request titles, categorized by release type.

Release Type Precedence

When multiple merge requests with different release types are found, the plugin follows this precedence order:

1. major (highest)
2. premajor
3. minor
4. preminor
5. patch
6. prepatch
7. prerelease (lowest)

This ensures that the most significant change determines the final release type.

License

MIT