@gitlab/semantic-release-merge-request-analyzer/README.md

Semantic release plugin to determine version based on GitLab merge request labels

# semantic-release-merge-request-analyzer

A [semantic-release](https://github.com/semantic-release/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

```bash
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`:

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

#### Custom Label Configuration

You can customize which labels trigger which release types:

```json
{
  "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:

```json
{
  "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